#  `add_text`

Add user-specified text strings to PDF pages
## Usage
> pdftl `<input>` `add_text` `<spec>...` `output` `<file>` `[<option>...]`

## Details
Add user-specified text strings to PDF pages.

Note: This operation requires the 'reportlab' library. If not
installed, run: `pip install pdftl[add_text]`.


A text specification (`<spec>`) has the format:

>  `[page range]<delimiter><text string><delimiter>[<options>]`

`<delimiter>` must be a single, non-alphanumeric character
(e.g., /, !, #).

### Dynamic Text Variables in text strings

The `<text string>` supports variable substitution using curly
braces {}, in one of the following formats.

1. Simple format: e.g., `{page}` gives the current page
number. Possible variables are:

   - `page`: The current page number (1-based index).

   - `n`: The sequence number (1-based index within the current spec)

   - `total`: The total number of pages in the PDF.

   - `filename`: The name of the input PDF file, including the extension
  (e.g., "document.pdf").

   - `filename_base`: The base name of the input PDF file,
  without the extension (e.g., "document").

   - `filepath`: The full path to the input PDF file.

   - `date`: The current date formatted as YYYY-MM-DD (e.g.,
  2025-12-12).

   - `time`: The current time formatted as HH:MM:SS (e.g.,
  13:53:41).

   - `datetime`: The current date and time in ISO 8601 format
  (e.g., 2025-12-12T13:53:41.123456).


2. Source Metadata (Pipeline): These variables track the original
source file of a page, even after operations like `cat` or `shuffle`.

   - `source_filename`: The filename of the specific source PDF this page came from.

   - `source_path`: The full file path of the source PDF.

   - `source_page`: The original page number in the source file.

   - `source_rotation`: The rotation of the source page (0, 90, 180, 270).

   - `source_width` / `source_height`: The dimensions of the source page.

   - `source_orientation`: "Portrait" or "Landscape".


3. Arithmetic & Formatting: Support for offsets and Python-style
padding. Useful for Bates stamping.
   - Offset: `{page+100}` starts numbering at 101.
   - Padding: `{page:06d}` produces "000001".
   - Combined: `{page+5000:06d}` produces "005001".

4. Complex: e.g., {total-page} gives the number of pages
remaining.  (for now, this is the only complex possibility).

5. Metadata: e.g., {meta:Title}. The metadata variables
`allow` you to insert information stored within the PDF
document's own metadata dictionary (`/Title`, `/Author`,
etc.) into your text.

The format for a metadata variable is: {meta:`<KeyName>`}
where `<KeyName>` is the exact, case-sensitive key found in
the PDF's document information dictionary (it corresponds to
the PDF keys like `/Title` after the leading slash is
stripped).

The available keys are determined by the contents of the PDF
itself, but common examples derived from the PDF
specification include: Title, Author, Subject, Keywords,
Creator, Producer, CreationDate. If the specified `<KeyName>`
does not exist in the PDF's metadata, the variable will be
substituted with an `empty` string.


6. Escaping: `{{...}}` renders a literal `{...}` string.


### Hyperlinks

You can create clickable hyperlinks within your text using standard
Markdown syntax: `[Display Text](URL)`. Dynamic variables are supported
in both the display text and the URL.

Example: `[Visit Page {page}](https://example.com/p{page})`
Escaping: Use `\[` and `\]` if you need literal brackets inside the text.


### Options

Options are passed as comma-separated key=value pairs inside
parentheses, e.g., (`position=bottom-center`, `size=10`).

#### Positioning and layout options

`position=<keyword>`: Preset position (top-left, center, mid-center,
bottom-right, etc.). Cannot be used with `x`/`y`.

`x=<dim>`, `y=<dim>`: Absolute coordinates.

`offset-x=<dim>`, `offset-y=<dim>`: Offset relative to the main
position.

Dimension values (`<dim>`) must include a unit (e.g., `10pt`,
`5cm`, `20%`) or default to points (pt). Supported units are
pt, in, cm, mm, and %.

`rotate`=`<float>`: Angle in degrees (e.g., 45).

#### Formatting options

`font=<string>`: Font name (e.g., Helvetica-Bold).

`size=<float>`: Font size in points.

`color=<string>`: Text color. 1, 3, or 4 space-separated
numbers between 0 and 1. Examples: `0.5` is gray,
`1 0 0` is red, and `1 0 0 .5` is semi-transparent red.

`bgcolor=<string>`: Background color. 1, 3, or 4 space-separated
numbers between 0 and 1.

`padding=<dim>`: Padding for background colored rectangle, if present

`linkcolor=<string>`: Color for hyperlinks (uses the same format as `color`).
Defaults to the main `color` if not set.

`align=<'left'|'center'|'right'>`: Horizontal alignment.
## Examples

> Add "Page X of Y" to the bottom-center of all pages
```
pdftl in.pdf add_text '1-end/Page {page} of {total}/(position=bottom-center, size=10, offset-y=10pt)' output out.pdf
```

> Add a large, rotated "DRAFT" watermark to odd pages
```
pdftl in.pdf add_text 'odd!DRAFT!(position=mid-center, font=Helvetica-Bold, size=72, rotate=45, color=0.8 0.8 0.8)' output out.pdf
```

> Add a header with the document's title to page 1
```
pdftl in.pdf add_text '1/Document: {meta:Title}/(x=1cm,y=28cm,font=Times-Bold,size=14)' output out.pdf
```

> Stamp pages with their original filename (useful in pipelines)
```
pdftl A.pdf B.pdf cat --- add_text '1-end/Source: {source_filename} (p.{source_page})/(position=bottom-left, size=8)' output out.pdf
```

> Apply a Bates stamp (starting at DEF-005001) to the bottom-right
```
pdftl in.pdf add_text '/DEF-{page+5000:06d}/(position=bottom-right, size=10, color=1 0 0)' output out.pdf
```

> Add a clickable Markdown link with a custom link color
```
pdftl in.pdf add_text '/Visit [Our Website](https://example.com)/(position=top-right, size=12, linkcolor=0 0 1)' output out.pdf
```

> Apply sequential sequence numbering that resets per specification
```
pdftl in.pdf add_text '1-3/Exhibit A-{n}/(position=top-left, size=10)' '4-6/Exhibit B-{n}/(position=top-left, size=10)' output out.pdf
```


**Tags**: in_place, text

*Source: pdftl.operations.add_text*

*Read online: [https://pdftl.readthedocs.io/en/stable/operations/add_text.html](https://pdftl.readthedocs.io/en/stable/operations/add_text.html)*

*Type: Operation*