# Arguments and options for the dita command

The dita command takes mandatory arguments to process DITA content. Subcommands can be used to manage plug-ins, or print information about the current configuration. A series of options are available to modify the command behavior or specify additional configuration parameters.

## Usage

To convert content from one format to another, specify the file to transform and the desired output format. If necessary, you can set additional configuration parameters with options.

> `dita` `--input` `=` file `--format` `=` name [ options ]

> `dita` `--project` `=` file [ options ]

Note:
Most dita command options support several syntax alternatives. All options can be specified with a GNU-style option keyword preceded by two hyphens. In many cases, Unix-style single-letter options (preceded by a single hyphen) are also available for brevity and backwards compatibility.

The dita command also supports a series of subcommands that can be used to manage plug-ins, or print information about the current configuration or version.

> `dita` `deliverables` file

> `dita` `init` template [ `--output` `=` dir ] [ options ]

> `dita` `install` [ { ID | URL | file } ]

> `dita` `plugins`

> `dita` `transtypes`

> `dita` `uninstall` ID

> `dita` `validate` `--input` `=` file [ options ]

> `dita` `version`

## Arguments

Each transformation requires you to specify at least the file to transform and the desired output format.

--input=file
-i file
  Specifies the main file for your documentation project.
  This argument corresponds to the common parameter args.input.
  Typically this is a DITA map, however it also can be a DITA topic if you want to transform a single DITA file. The path can be absolute, relative to args.input.dir, or relative to the current directory if args.input.dir is not defined.
--format=name
-f name
  Specifies the output format (transformation type).
  This argument corresponds to the common parameter transtype.
  To list the formats that are currently available in your environment, use dita transtypes.
  You can create plug-ins to add new output formats; by default, the following values are available:
  - dita
  - eclipsehelp
  - html5
  - htmlhelp
  - markdown, markdown_gitbook, and markdown_github
  - pdf
  - xhtml
  Tip:
  See Output formats for sample command line syntax and more information on each transformation.
--project=file
  Publish a project file with multiple deliverables.
  You can add the --deliverable option to specify a single deliverable in the project.
  For more information, see Publishing with project files.

## Subcommands

deliverables file
  Show a list of the available deliverables in the specified project file.
init template
  Initialize a project with files from the specified template.
  The folder hierarchy in the template will be copied to the current working directory by default. To write the files to a different location, add the --output option and specify the desired path. The directory will be created if it doesn’t exist. If any of the template files are already present, an error will appear.
init --list
  Show a list of the available project templates.
  The entries in this list may be passed as arguments to the init subcommand.
install { ID | URL | file }
  Install a single plug-in ID from the registry at dita-ot.org/plugins (or a local registry), from a remote URL, or a local ZIP file.
  Note:
  The --force option can be passed as an additional option to the installation subcommand to force-install an existing plug-in: dita install plug-in-zip --force.
  Tip:
  The dita install command uses a network connection to install plug-ins from the configured registry or process remote referenced resources. In environments where an HTTP proxy is used to establish a network connection, you can provide the proxy configuration via the `ANT_OPTS` environment variable. For more information, see Configuring proxies.
install
  If no ID, URL, or file argument is provided, the installation process reloads the current set of plug-ins from the plugins directory (or any custom locations defined via the pluginsdir property in the configuration.properties file in the config directory). This approach can be used to add or remove multiple plug-ins at once, or any individual plug-ins you have already copied to (or removed from) the plug-in directories. Any plug-ins added or removed in the process will be listed by their plug-in ID.
plugins
  Show a list of the currently installed plug-ins.
transtypes
  Show a list of the available output formats (transformation types).
  The entries in this list may be passed as values to the --format argument.
uninstall ID
  Remove the plug-in with the specified ID.
  For a list of the currently installed plug-in IDs, use dita plugins.
  Attention:
  The uninstall subcommand also removes the corresponding plug-in directory from the plugins folder.
validate
  Validate input file. No output is generated.
version
  Print version information and exit.

## Options

--debug
-d
  Debug logging prints considerably more additional information. The debug log includes all information from the verbose log, plus details on Java classes, additional Ant properties and overrides, pre-processing filters, parameters, and stages, and the complete build sequence. Debug logging requires additional resources and can slow down the build process, so it should only be enabled when further details are required to diagnose problems.
--filter=files

  Specifies filter file(s) used to include, exclude, or flag content. Relative paths are resolved against the current directory and internally converted to absolute paths.

  Note:

  To specify multiple filter files, use the system path separator character to delimit individual file paths (semicolon ‘`;`’ on Windows, and colon ‘`:`’ on macOS and Linux) and wrap the value in quotes:

  `--filter="filter1.ditaval;filter2.ditaval;filter3.ditaval"`

  As of DITA-OT 3.6, the --filter option can also be passed multiple times:

  `--filter=filter1.ditaval --filter=filter2.ditaval --filter=filter3.ditaval`

  DITAVAL files are evaluated in the order specified, so conditions specified in the first file take precedence over matching conditions specified in later files, just as conditions at the start of a DITAVAL document take precedence over matching conditions later in the same document.

--help
-h
  Print a list of available arguments, options, and subcommands.
--logfile=file
-l file
  Write logging messages to a file.
  Note:
  If processing is successful, nothing is written to the log, so the file will be empty if there are no errors or warnings. To include informational messages in the log, add the --verbose option (or -v).
--logger=json

  Generate a structured log in JSON format. Each log message generates a JSON object on its own line. JSON logging disables colored output.

  If log is written to a file with --logfile, the log will be generated as a JSON array where each log message is a JSON object as an array item.

--no-color
  By default, DITA-OT prints certain log messages to the console in color. In terminal environments that do not support colored output, the ANSI color escape codes will be shown instead. To deactivate colored output, pass the --no-color option to the dita command, or set the `TERM=dumb` or `NO_COLOR` environment variables.
--output=dir
-o dir

  Specifies the path of the output directory; the path can be absolute or relative to the current directory.

  This option corresponds to the common parameter output.dir.

  By default, the output is written to the out subdirectory of the current directory.

--parameter=value
-D parameter=value
  Specify a value for a DITA-OT or Ant build parameter.
  The GNU-style --parameter=value form is only available for parameters that are configured in the plug-in configuration file; the Java-style -D form can also be used to specify additional non-configured parameters or set system properties.
  Parameters not implemented by the specified transformation type or referenced in a .properties file are ignored.
  Tip:
  If you are building in different environments where the location of the input files is not consistent, set args.input.dir with the dita command and reference its value with `${args.input.dir}` in your .properties file.
--propertyfile=file
  Use build parameters defined in the referenced .properties file.
  Build parameters specified on the command line override those set in the .properties file.
--repeat=N
  Repeat the transformation N number of times.
  This option can be used by plug-in developers to measure performance. To run a conversion five times, for example, use --repeat=5. The duration of each execution will appear in the console when the final transformation is complete.

      $ dita --input=path/to/sample.ditamap --format=html5 \
             --repeat=5
      1 11281ms
      2 4132ms
      3 3690ms
      4 4337ms
      5 3634ms

--resource=file
-r file
  Specifies resource files.
  This argument corresponds to the common parameter args.resources.
  Resource files can be used to convert partial documentation sets by processing input with additional information.
  For example, to process a single topic file with a map that contains key definitions, use a command like this:

      dita --input=topic.dita --resource=keys.ditamap --format=html5

  To convert a chapter map to HTML5 and insert related links from relationship tables in a separate map, use:

      dita --input=chapter.ditamap --resource=reltables.ditamap --format=html5

--stacktrace
  When processing fails on an error condition, Java stack trace is printed for debugging. Only applies when --verbose or --debug options are set.
--temp=dir
-t dir
  Specifies the location of the temporary directory.
  This option corresponds to the common parameter dita.temp.dir.
  The temporary directory is where DITA-OT writes intermediate files that are generated during the transformation process.
--theme=file
  Publish PDF output with a theme configuration file.
  For more information, see PDF themes.
--verbose
-v
  Verbose logging prints additional information to the console, including directory settings, effective values for Ant properties, input/output files, and informational messages to assist in troubleshooting.