Command Line Interface (CLI) Reference

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. This page covers the commands and options the antora command accepts and shows several examples.

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> [option] <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. Options are prefixed with two hyphens (--).

  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

Required base command.

generate

Generate the documentation site specified by the <playbook>. This command is implicitly executed when 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 and Environment Variables
CLI Option Purpose Format Default

--attribute <attribute>

A global document attribute to set on each AsciiDoc document. May be specified multiple times. The value must adhere to the form name or name=value. Append @ to the value to allow it to be overridden in a document.

String, String=String

not set

--cache-dir <dir>

Directory where remote content sources git repositories and UI bundles are cached. Overrides the cache_dir key in a playbook.

Use environment variable ANTORA_CACHE_DIR as an alternative to the command line option.

String

<user cache>/antora

--clean

Removes the output directory before generating the site. Overrides the clean key in a playbook.

Boolean

false

--generator

The site generator library (package name) or script (path) to use. Must export a function with the signature generateSite(args, env). Intended for advanced users comfortable with the inner workings of Antora. Effectively substitutes Antora’s entire pipeline with a user-defined function.

String

@antora/site-generator-default

--git-credentials-path

An alternate path to a file that contains credentials for git matching the format used by git-credential-store.

The path can also be passed an an environment variable GIT_CREDENTIALS_PATH instead of the command line option. The contents of such a credentials file can also be passed as an environment variable named GIT_CREDENTIALS.

String

not set

--google-analytics-key

The API key for Google Analytics / Tag Manager. Setting this option implicitly enables the Google Analytics / Tag Manager embed code when using the default UI. Overrides the Google Analytics key in a playbook.

Use environment variable GOOGLE_ANALYTICS_KEY as an alternative to the command line option.

String

not set

--fetch

Updates the cache by downloading updates from remote content sources git repositories and UI bundles (if snapshot is true). Overrides the fetch key in a playbook.

Boolean

false

--quiet

Do not write any messages to stdout.

Boolean

false

--redirect-facility <facility>

Facility for handling URL redirects calculated from page-aliases. The supported facilities are disabled, netlify, nginx, and static. Overrides the redirect_facility key in a playbook.

String

static

-r, --require <name>

Preload the specified library or script. May be specified multiple times.

String

not set

--silent

Suppress all messages, including warnings and errors.

Boolean

false

--stacktrace

Print the stacktrace to the console if the application fails.

Boolean

false

--title <title>

Specify the title of the site. Overrides the site title key in a playbook.

String

not set

--to-dir <dir>

Directory where the site files are published. Overrides the output dir key in a playbook.

String

build/site

--ui-bundle-url <bundle>

Specifies the URL or filesystem path to a UI bundle. Overrides the ui bundle url key in a playbook.

String

not set

--url <url>

Base URL of the published site. The URL should not include a trailing slash. Overrides the site url key in a playbook.

Use environment variable URL as an alternative to the command line option.

String

not set

-v, --version

Output the Antora version information.

Built-in

n/a

-h, --help

Output the command usage 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 antora-playbook.yml

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

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

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

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

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

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

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

Example 5: Have the generate command download updates
$ antora --fetch antora-playbook.yml

After running the generate command the first time, subsequent runs will use cached copies of remote resources by default (effectively running offline). Example 5 shows how to run the generate command so it will download (fetch) updates to remote content sources and download a remote UI bundle again.