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>

All functions start with a base call to Antora (antora).
The command tells Antora what operation to perform.
Additional options can be specified after a command.
Positional arguments, such as the name of the playbook file, are specified last.
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 (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.	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.	String	not set
--fetch	Download updates from remote resources (including content repositories 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 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-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 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 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.