Skip to main content

Section 5.2 The PreTeXt-CLI

Here we will outline the functionality of the PreTeXt-CLI. Instructions for installing this command line interface can be found in Section 2.1.

First, to verify that you have the CLI installed correctly, enter the following command in a terminal:

pretext --version

You should get back something like 0.4.1. If this doesn't work, try starting the previous line with python -m, which might help if your PATH is not set up correctly. In fact, prepending python -m to all commands in this section might be necessary, depending on your system.

You can upgrade the CLI to the most recent version through PIP using the command:

pip install pretextbook --upgrade

For quick hints about what you can do, the CLI has built-in help. You can access this by entering pretext --help or pretext build --help (replacing build with new or view or etc.)

Subsection 5.2.1 Starting a New Project: pretext new

To generate a new book or article, from the folder in which you want to project located, type:

pretext new book

This creates a new book in the folder “new-pretext-project” which you can safely rename. For a new article, use pretext new article.

The new project includes a file “project.ptx” which we call the project manifest. This is an XML file that specifies options for converting your source into different target outputs. We will describe the contents of this file more in a bit.

Subsection 5.2.2 Converting: pretext build

To convert your source into one of the available output formats, say HTML, run the command:

pretext build html

Here “html” is the @name of one of the targets in the project manifest (project.ptx).

Subsection 5.2.3 Viewing output: pretext view

After you convert your source into, say HTML, you can view the output using the command:

pretext view html

This will direct you to open a local server at a provided address (perhaps http://localhost:8000). Replace “html” in the above with other build targets as appropriate.

The pretext view command accepts a useful option for small projects that allow you to automatically rebuild your source every time you save it. Try:

pretext view html --watch

This currently only supports HTML-format targets.