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

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

--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 cached files are stored (git repositories clones and the UI bundle). Overrides the cache dir value specified in the playbook.

String

<user’s cache>/antora

--clean

Remove the output directory before publishing the site.

Boolean

false

--generator

The site generator library or script 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

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

String

no set

--pull

Download updates to remote resources (content sources and UI bundle).

Boolean

false

--quiet

Do not write any messages to stdout.

Boolean

false

-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 value specified in the playbook.

String

not set

--to-dir <dir>

Directory where the site is generated. Overrides the output dir value specified in the playbook.

String

build/site

--ui-bundle-url <bundle>

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

String

not set

--url <url>

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

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 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 auto-detected playbook test-site.yml. 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 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-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 current working directory) and the site files written to it.

Example 5: Have the generate command download updates
$ antora --pull site.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.