Command line (LaTeX2e unofficial reference manual (October 2018))

## Command line

Synopsis (from a terminal command line):

    pdflatex options argument

Run LaTeX on argument. In place of `pdflatex` you can also use `xelatex`, or `lualatex`, or `dviluatex`, or `latex`.

For example, this will run LaTeX on the file `thesis.tex`, creating the output `thesis.pdf`.

    pdflatex thesis

Note that `.tex` is the default file extension.

pdfTeX is a development of the original TeX program, as are XeTeX and LuaTeX (see TeX engines). They are completely backward compatible. But the original program had a custom output format, DVI, while the newer ones can output directly to PDF. This allows them to take advantage of the extra features in PDF such as hyperlinks, support for modern image formats such as JPG and PNG, and ubiquitous viewing programs. In short, if you run `pdflatex` or `xelatex` or `lualatex` then you will by default get PDF and have access to all its modern features. If you run `latex`, or `dvilualatex`, then you will get DVI. The description here assumes pdfLaTeX.

See Command line options, for a selection of the most useful command line options. As to argument, the usual case is that it does not begin with a backslash, so the system takes it to be the name of a file and it compiles that file. If argument begins with a backslash then the system will interpret it as a line of LaTeX input, which can be used for special effects (see Command line input).

If you gave no arguments or options then `pdflatex` prompts for input from the terminal. You can escape from this by entering `<control>-D`.

If LaTeX finds an error in your document then by default it stops and asks you about it. See Recovering from errors for an outline of what to do.

### Command line options

These are the command-line options relevant to ordinary document authoring. For a full list, try running ‘`latex --help`’ from the command line.

With many implementations you can specify command line options by prefixing them with ‘`-`’ or ‘`--`’. This is the case for both TeX Live (and MacTeX) and MiKTeX. We will use both conventions interchangeably.

`-version`

  Show the current version, like ‘`pdfTeX 3.14159265-2.6-1.40.16 (TeX Live 2015/Debian)`’ along with a small amount of additional information, and exit.

`-help`

  Give a brief usage message that is useful as a prompt and exit.

`-interaction=mode`

  TeX compiles a document in one of four interaction modes: `batchmode`, `nonstopmode`, `scrollmode`, `errorstopmode`. In errorstop mode (the default), TeX stops at each error and asks for user intervention. In batch mode it prints nothing on the terminal, errors are scrolled as if the user hit `<return>` at every error, and missing files cause the job to abort. In nonstop mode, diagnostic message appear on the terminal but as in batch mode there is no user interaction. In scroll mode, TeX only stops for missing files or keyboard input.

  For instance, starting LaTeX with this command line

      pdflatex -interaction=batchmode filename

  eliminates most terminal output.

`-jobname=string`

  Set the value of TeX’s `jobname` to the string. The log file and output file will then be named `string.log` and `string.pdf`.

  When you run ``pdflatex` options argument`, if argument does not start with a backslash then TeX considers it the name of a file to input. Otherwise it waits for the first `\input` instruction and the name of the input file will be the job name. This is used to name the log file the output file. The `jobname` option overrides that process and directly specifies the name. See Command line input for an example of its use.

`-output-directory=directory`

  Write files in the directory directory. It must already exist.

`--shell-escape`
`--no-shell-escape`
`--enable-write18`
`--disable-write18`

  Enable or disable `\write18{shell command}`. The first two options are for with TeX Live or MacTeX while the second two are for MiKTeX.

  Sometimes you want to run external system commands from inside a LaTeX file. For instance the package `sagetex` allows you to have the mathematics software system Sage do calculations or draw graphs and then incorporate that output in your document. For this TeX provides the `\write18` command.

  But with this functionality enabled, security issues could happen if you compiled a LaTeX file from the Internet. By default `\write18` is disabled. (More precisely, by default TeX Live, MacTeX, and MiKTeX only allow the execution of a limited number of TeX-related programs, which they distribute.)

  If you invoke LaTeX with the option `no-shell-escape`, and in your document you call `\write18{ls -l}`, then you do not get an error but the log file says ‘`runsystem(ls -l)...disabled`’.

`-halt-on-error`

  Stop processing at the first error.

`-file-line-error`
`-no-file-line-error`

  Enable or disable `filename:lineno:error`-style error messages. These are only available with TeX Live or MacTeX.

### Command line input

As part of the command line invocation `pdflatex options argument` you can specify arbitrary LaTeX input by starting argument with a backslash. This allows you to do some special effects.

For example, this file (which uses the `hyperref` package for hyperlinks) can produce two kinds of output, one for paper and one for a PDF.

    \ifdefined\paperversion        % in preamble
    \newcommand{\urlcolor}{black}
    \else
    \newcommand{\urlcolor}{blue}
    \fi
    \usepackage[colorlinks=true,urlcolor=\urlcolor]{hyperref}
      ...
    \href{https://www.ctan.org}{CTAN}  % in body
      ...

Compiling this document `book.tex` with the command line `pdflatex book` will give the ‘`CTAN`’ link in blue. But compiling it with `pdflatex "\def\paperversion{}\input book.tex"` has the link in black. (Note the use of double quotes to prevent interpretation of the symbols by the command line shell; your system may do this differently.)

In a similar way, from the single file `main.tex` you can compile two different versions.

    pdflatex -jobname=students "\def\student{}\input{main}"
    pdflatex -jobname=teachers "\def\teachers{}\input{main}"

The `jobname` option is there because otherwise both files would be called `main.pdf` and the second would overwrite the first.

A final example. This loads the package `graphicx` with the option `draft`

    pdflatex -jobname=aa "\RequirePackage[draft]{graphicx}\input{aa.tex}"

so the graphic files are read for their size information but not incorporated into the PDF. (The `jobname` option is there because otherwise the output file would be `graphicx.pdf`, as `\RequirePackage` does an `\input` of its own.)

### Recovering from errors

If LaTeX finds an error in your document then it gives you an error message and prompts you with a question mark, `?`. For instance, running LaTeX on this file

    \newcommand{\NP}{\ensuremath{\textbf{NP}}}
    The \PN{} problem is a million dollar one.

causes it show this, and wait for input.

    ! Undefined control sequence.
    l.5 The \PN
               {} problem is a million dollar one.
    ?

The simplest thing is to enter ‘`x`’ and `<return>` and fix the typo. You could instead enter ‘`?`’ and `<return>` to see other options.

There are two other error scenarios. The first is that you forgot to include the `\end{document}` or misspelled it. In this case LaTeX gives you a ‘`*`’ prompt. You can get back to the command line by typing `\stop` and `<return>`.

The last scenario is that you mistyped the file name. For instance, instead of `pdflatex test` you might type `pdflatex tste`.

    ! I can't find file `tste'.
    <*> tste

    (Press Enter to retry, or Control-D to exit)
    Please type another input file name:

The simplest thing is to enter `<Control>` and ‘`d`’ (holding them down at the same time), and then retype the correct command line.