CPDF(1)

📦
version 2.9 · 2 versions
, in epel 10, epel 9, fedora 43, fedora 44, ubuntu stonking

💖 cpdf(1) — General Commands Manual 💖

okay bestie, pull up a chair, grab a boba, because we're about to get SO cozy with cpdf(1). this is the manpage for the cpdf command line tools and it's genuinely iconic, no cap.

✨ NAME ✨

cpdf — PDF command line tools. that's it. that's the name. short, sweet, serves.

✨ SYNOPSIS ✨

simple operation, the everyday slay:

cpdf [in.pdf] [operation] [options] [-o out.pdf]

operation on a password-protected file, iykyk:

cpdf in.pdf [user=<password>] [owner=<password>] ...  [-o out.pdf]

multiple operations, one after another (chaining, we love to see it):

cpdf [in.pdf] [operation] [options] AND [operation] [options] AND ... [-o out.pdf]

✨ DESCRIPTION ✨

Cpdf is an AGPL-licensed command line tool for processing PDF files. 💅 literally does it all.

the rest of this document gives a brief description of each command line operation and option. the file cpdfmanual.pdf — which you should find installed on your system, or otherwise at https://www.coherentpdf.com/cpdfmanual.pdf — gives the full usage details. so if this page leaves you wanting more, that's where the full tea lives. 🫖

the sections in this document follow the chapters of cpdfmanual.pdf, for easy cross-referencing. cute, organized, main character energy. ✨

🌈 1. BASIC USAGE 🌈

the starter pack of flags

  • -version — print the Cpdf version number. just, like, who are you. in a good way.
  • -help, –help — gives links to sources of help. we all need a little help sometimes bestie. 🫶
  • -summary — lists and describes very briefly each command line option. the tl;dr of tl;drs.
  • -o <filename> — the output filename. > ⚠️ beware of writing back to the input file. that's not a vibe check, that's a genuine warning. don't do it.
  • -i <filename> — Cpdf automatically treats any filename ending with .pdf (any case) as an input PDF. but if your file doesn't end with .pdf, you can supply the file with -i instead. inclusivity! 💖
  • -range <range> — gives the range of pages to be affected by an operation. by default, all pages are affected. the range may be specified without -range simply by writing it directly after the filename it relates to. example ranges: “2” “1-5” “1,2,3-end” “odd” “NOT1-5”. see cpdfmanual.pdf for a full description. so many options, so many looks. 💅
  • -progress — show which operations and on which pages they are operating, as it happens, on standard error. live updates, we're streaming. 📺
  • -keep-version — keep the PDF version of the input document even if features are used which would otherwise make it increase. don't let anyone force you to change. ✋
  • -fast — presume ISO-compliant content streams when processing page content. this is faster, because it does not involve re-parsing whole streams to add content. speed. 🏎️
  • -idir <path> — add a whole directory of PDFs as inputs. bulk, we love a bulk moment.
  • -idir-only-pdfs — restrict -idir to only files ending in .pdf (any case). > must appear before -idir. order matters, bestie.
  • -recrypt — re-encrypt output files using the same encryption parameters (if any) as the input file. privacy, but make it consistent. 🔒
  • -decrypt-force — allow the output file to be written decrypted even if permissions would otherwise prevent it. force, but make it authorized. 💀
  • -stdout — write the output file to standard output instead of to a file with -o. pipe it, slay it.
  • -stdin — read the input PDF from standard input instead of from a named file. the other end of the pipe. 🫶
  • -stdin-user <password> — supply the user password for the PDF which is from standard input.
  • -stdin-owner <password> — supply the owner password the the PDF which is from standard input. (yes it says "the the", that's canon, we don't edit the queen. 👑)
  • -producer <string> — set the producer of the output file. put your name on it, it's your art.
  • -creator <string> — set the creator of the output file. even more credit. ✨
  • -change-id — change the PDF's ID field when writing the output file. fresh identity, fresh start. 🦋
  • -l — linearize the PDF when writing. > requires a linearizer to be supplied with -cpdflin.
  • -cpdflin <path> — give the path of an external linearizer. for example, Qpdf.
  • -keep-l — keep the linearization status (either linearized or not) of the input file upon output. > requires a linearizer to be supplied with -cpdflin.
  • -no-preserve-objstm — do not preserve existing object streams when writing the output file. note that -create-objstm and -no-preserve-objstm may be used together — the effect is then to redo all object streams. combo move. 🔥
  • -create-objstm — create new object streams when writing the output file. note that -create-objstm and -no-preserve-objstm may be used together — the effect is then to redo all object streams. same combo, other direction. 💅
  • -args <filename> — read command line arguments from the given file by direct textual substitution into the command line, prior to any other processing.
  • -args-json <filename> — read command line arguments from a JSON file consisting of a single array of strings. json girlies rise. 🧚
  • -utf8 — read and write string data as UTF8. almost always the sensible option, and will become the default in a future version. ahead of its time, honestly. ⭐
  • -stripped — convert string output to 7 bit ASCII by dropping any high characters. > to be used with caution. 😭
  • -raw — perform no processing on string outputs. raw, unfiltered, no edits. periodt.
  • -gs <path> — a very few of Cpdf's functions rely upon the gs command. its path may be supplied with -gs.
  • -gs-malformed — this option is used to allow Cpdf to call out to the gs command to pre-process badly malformed files as a last resort. emergency mode, bestie. 🚨
  • -gs-malformed-force — see cpdfmanual.pdf for details of this fragile command. fragile. handle with care. 🙈
  • -gs-quiet — do not show the output of gs when used. shhh. 🤫
  • -error-on-malformed — do not attempt to reconstruct malformed files by any method, but exit with an error. no fixing, just honesty. 💀

🎀 2. MERGING AND SPLITTING 🎀

🌸 Merging 🌸

cpdf -merge in1.pdf [<range>] in2.pdf [<range>] [<more names/ranges>]
[-collate] [-collate-n <n>] [-retain-numbering] [-merge-add-bookmarks
[-merge-add-bookmarks-use-titles]] [-remove-duplicate-fonts]
[-process-struct-trees] [-subformat <subformat>] -o out.pdf

the -merge operation allows the merging of several files into one. ranges can be used to select only a subset of pages from each input file in the output. the output file consists of the concatenation of all the input pages in the order specified on the command line. actually — plot twist — the -merge can be omitted, since this is the default operation of Cpdf. it's giving "effortless". 💅

  • -collate — instead of ordinary operation, take the first page from the first document, then the first from the second and so on. then the second page from the first document and on until all pages are exhausted. shuffling the deck, iconic. 🃏
  • -collate-n <n> — like -collate, but in chunks of more than one page. chunkier collate.
  • -retain-numbering — keep the page numbering of each input file intact, rather than renumbering the pages in the output document beginning at 1. no renumbering, no notes. ✋
  • -merge-add-bookmarks [-merge-add-bookmarks-use-titles] — add a top-level bookmark for each file, using the filename. the option -merge-add-bookmarks-use-titles, when used in conjunction with -merge-add-bookmarks, uses the titles from document metadata instead. cute little tabs for days. 🔖
  • -remove-duplicate-fonts — ensures that fonts used in more than one input appear only once in the output. decluttering, we stan. 🧹
  • -process-struct-trees — merge input structure trees in the output.
  • -subformat <subformat> — if -subformat “PDF/UA-2” is given, together with -process-struct-trees, Cpdf will add a top-level Document structure tree element.

🦋 Portfolios 🦋

a PDF portfolio is a special kind of PDF which contains other documents (PDF and otherwise) within it. support is mostly limited to Adobe products at time of writing. it's a whole little world in there. 🌍

cpdf -portfolio in.pdf -pf <filename> [-pfd <string>] [-pfr
<relationship>] [-pf ...]  -o out.pdf

the input in.pdf here is the main file. you can build a blank one with -create-pdf.

  • -pf <filename> — the filename for each file to include in the portfolio.
  • -pfd <description> — the description for the file (> must appear after -pf).
  • -pfr <relationship> — the so-called relationship for the file (> must appear after -pf). it's complicated, but we support it. 💜

✂️ Splitting ✂️

we can split an input PDF into its constituent pages, and output one PDF for each page or each chunk of pages.

cpdf -split in.pdf [-chunk <n>] [-process-struct-trees] [-utf8] -o <format>

the output format has many options (see cpdfmanual.pdf for details). but the simplest is just to number the outputs in sequence. for example cpdf in.pdf -o out%%%.pdf will produce out001.pdf, out002.pdf and so on. look at them go. 🌈

  • -chunk <n> — choose a chunk size other than 1.
  • -process-struct-trees — split the input document's structure tree into the output documents.
  • -utf8 — this option may be required in the case of some output formats. see cpdfmanual.pdf for details.

🔖 Splitting on bookmarks 🔖

cpdf -split-bookmarks <level> in.pdf [-process-struct-trees] [-utf8] -o <format>

split on bookmark boundaries at a given level, instead of splitting on each page. level 0 is top level, level 1 next, and so on. see above for format details. following the vibes of your bookmarks, respectfully. 💖

  • -process-struct-trees — split the input document's structure tree into the output documents.
  • -utf8 — this option may be required in the case of some output formats. see cpdfmanual.pdf for details.

⭐ Splitting to a given size ⭐

cpdf -split-max <n> in.pdf [-process-struct-trees] [-utf8] -o <format>

split the file, if possible, to a maximum file size (in bytes) for each output PDF. see above for format details. keeping it bite-sized, fr fr.

  • -process-struct-trees — split the input document's structure tree into the output documents.
  • -utf8 — this option may be required in the case of some output formats. see cpdfmanual.pdf for details.

💫 Interleaved splitting 💫

we can use -spray to write the split pages to more than one named output file. when Cpdf runs out of output files, it adds the next page to the first output file, and so on until all input pages are exhausted. round robin but make it pages. 🔄

cpdf -spray in.pdf [-process-struct-trees] [-utf8] -o a.pdf [-o b.pdf [-o ...]]
  • -process-struct-trees — split the input document's structure tree into the output documents.
  • -utf8 — this option may be required in the case of some output formats. see cpdfmanual.pdf for details.

🦋 3. PAGES 🦋

ok bestie this chapter is all about moving pages around, scaling them, rotating them, flipping them — the whole glow-up menu. let's go 💅

cpdf -scale-page "<x scale> <y scale>" in.pdf [<range>] [-fast]
[<position>] -o out.pdf

Scale pages in the given range by the given factor e.g "2 2". See Chapter 8 for information on positions. (yes queen, chapter 8 is where the positions live, we'll get there 💖)

cpdf -scale-to-fit "<x size> <y size>" in.pdf [<range>] [-fast]
[-prerotate] [<position>] [-scale-to-fit-scale <scale>]
[-scale-to-fit-rotate-clockwise] [-scale-to-fit-rotate-anticlockwise] -o
out.pdf

Scale pages in the given range to fit the given size e.g "a4paper" or "10in 7in", without altering the aspect ratio. By default the content will be centered on the new page. See Chapter 8 for information on positions.

  • -scale-to-fit-scale <n> — scale to a proportion of the available area instead of filling it. like, 0.9 for 90 percent. so close to full but leaving a lil margin, very demure 🎀
  • -scale-to-fit-rotate-clockwise, -scale-to-fit-rotate-anticlockwise — automatically rotate the page to maximise use of area. it's giving "make it fit, bestie" 🔄
  • -prerotate — remove any viewing rotation before beginning. clean slate energy ✨
cpdf -stretch "<x size> <y size>" in.pdf [<range>] [-fast] -o out.pdf

Scale pages without regard to aspect ratio. yeah she's gonna get squished or stretched, no thoughts, no proportions 💀

cpdf -center-to-fit "<x size> <y size>" in.pdf [<range>] [-fast] -o
out.pdf

Center each page on a new page size, without scaling it. just vibing in the middle, untouched 🌸

cpdf -scale-contents <scale> in.pdf [<range>] [<position>] [-fast] -o
out.pdf

Scale the content of pages by a given factor, without changing the size of the page. See the end of this chapter for position. (the paper stays, the stuff on it grows 📈)

cpdf -shift "<shift x> <shift y>" in.pdf [<range>] [-fast] -o out.pdf

Shift the content of pages by a given displacement. sliding into a new spot, no cap 🛝

cpdf -shift-boxes "<shift x> <shift y>" in.pdf [<range>] -o out.pdf

Shift the boxes of a page by a given displacement, without moving the content. the frame moves, the art stays. iconic contrast ✨

cpdf -rotate <angle> in.pdf [<range>] -o out.pdf

Change the PDF viewing rotation of pages to 0, 90, 180 or 270 degrees clockwise.

cpdf -rotateby <angle> in.pdf [<range>] -o out.pdf

Change the PDF viewing rotation of pages by 0, 90, 180 or 270 degrees clockwise. (so -rotate sets it, -rotateby adds to it — iykyk 🔥)

cpdf -upright in.pdf [<range>] [-fast] -o out.pdf

The -upright operation does whatever combination of -rotate and -rotate-contents is required to change the rotation of the document to zero without altering its appearance. In addition, it makes sure the media box has its origin at (0,0), changing other boxes to compensate. she does it ALL and makes it look effortless 👑

cpdf -rotate-contents <angle> in.pdf [<range>] [-fast] -o out.pdf

Rotates the content of the page around its center point by the given angle.

cpdf -hflip in.pdf [<range>] [-fast] -o out.pdf

Flip page content horizontally. mirror moment 🪞

cpdf -vflip in.pdf [<range>] [-fast] -o out.pdf

Flip page content vertically. upside-down era 🙃

cpdf -[media | crop | art | trim | bleed]box <boxspec> in.pdf [<range>]
-o out.pdf

Set the media, crop, art, trim or bleed box. For example -cropbox "50 50 300 200" sets minx 50, miny 50, width 300, height 200. To use absolute numbers instead of width and height, prefix with a question mark, writing "?50 50 350 250" instead. (the ? is like "bestie these are absolutes, don't @ me") ❓

cpdf -remove-[crop | art | trim | bleed]box in.pdf [<range>] -o out.pdf

Remove a crop, art, trim or bleed box from pages. gone. deleted. no trace 💨

cpdf -frombox <boxname> -tobox <boxname> in.pdf [<range>]
[-mediabox-if-missing] -o out.pdf

Copy a box to another. For example from /TrimBox to /CropBox. box-to-box pipeline, so slay 🎁

  • -mediabox-if-missing — use media box, rather than failing, if the -frombox is missing. (no tantrum, just fall back gracefully 🫶)
cpdf -hard-box <boxname> in.pdf [<range>] [-fast] [-mediabox-if-missing]
-o out.pdf

Create a hard box for a given box name — that is to say, one which clips its content. hard box = hard boundaries, she doesn't let anything spill out 🚧

cpdf -show-boxes in.pdf [<range>] [-fast] -o out.pdf

Show the media, crop, art, trim, and bleed boxes in Red, Green, Blue, Orange and Pink respectively. a whole rainbow of boundaries 🌈

cpdf -trim-marks in.pdf [<range>] [-fast] -o out.pdf

Add trim marks to a PDF. The trim box must be present. (no trim box, no trim marks, them's the rules ✂️)

🔐 4. ENCRYPTION AND DECRYPTION 🔐

ok this is the "who's allowed to see/touch what" chapter. very main character, very gatekeeping, but make it security 💅

cpdf -encrypt <method> [-pw=]<owner password> [-pw=]<user password>
in.pdf [-no-encrypt-metadata] <permissions> -o out.pdf

Encrypt a document given the method (e.g AES256ISO for modern usage), owner and user passwords, and optionally permissions. E.g cpdf -encrypt AES256ISO secret "" in.pdf -o out.pdf.

  • -no-encrypt-metadata — do not encrypt metadata (AES encryption only).
  • -pw=<password> — useful if a password may begin with a dash. (so the parser doesn't get confused and think your password is a flag, bestie 🎀)

Permissions (pick your limits, queen):

  • -no-edit — cannot change the document.
  • -no-print — cannot print the document.
  • -no-copy — cannot select or copy text or graphics.
  • -no-annot — cannot add or change form fields or annotations.
  • -no-forms — cannot edit form fields.
  • -no-extract — cannot extract text or graphics.
  • -no-assemble — cannot, for example, merge files.
  • -no-hq-print — cannot print high-quality.
Note: Adobe Acrobat and Adobe Reader may show slightly different permissions in info dialogues — this is a result of policy changes and not a bug in Cpdf. You may need to experiment. fr fr, don't come for cpdf, she's innocent 😭
cpdf -decrypt in.pdf owner=<owner password> [-decrypt-force] -o out.pdf

Decrypt a document, given its owner password.

  • -decrypt-force — decrypt even without the owner password, using just the user password. The user password is often blank. (lowkey wild but okay, she said "I'll allow it" 🙈)

🗜️ 5. COMPRESSION 🗜️

shrinking files is self-care, periodt ✨

cpdf -decompress in.pdf [-just-content] [-jbig2dec <path>] -o out.pdf

Decompress the streams in a PDF file, for instance to manually inspect it. (unzip it like "let me see your true form" 👀)

  • -just-content — only decompress page content streams.
  • -jbig2dec <path> — give the path to the jbig2dec program which Cpdf uses, if available, to decompress JBIG2 streams.
cpdf -compress in.pdf -o out.pdf

Compress any streams which are uncompressed using the FlateDecode method, with the exception of metadata streams. (metadata gets to stay unbothered 🎀)

cpdf -squeeze in.pdf [-squeeze-log-to <filename>] [-squeeze-no-pagedata]
-o out.pdf

Squeeze a file by coalescing like objects, and various other methods. she's squeezing it like a lemon, getting every last drop 🍋

  • -squeeze-log-to <filename> — write the squeeze log to file rather than standard output.
  • -squeeze-no-pagedata — avoid processing page data, making the squeeze process much faster at the cost of a little compression. speed over squeeze, a tradeoff bestie ⚡
cpdf -remove-article-threads in.pdf -o out.pdf

Remove article threads.

cpdf -remove-page-piece in.pdf -o out.pdf

Remove page piece information.

cpdf -remove-web-capture in.pdf -o out.pdf

Remove web capture data.

cpdf -remove-procsets in.pdf -o out.pdf

Remove ProcSets, a now-irrelevant data structure from early PDFs. ancient relic, we don't know her anymore 💀

cpdf -remove-output-intents in.pdf -o out.pdf

Remove output intents, a colour-matching system for documents intended to be printed.

🔖 6. BOOKMARKS 🔖

the navigation chapter!! bookmarks are literally the little side quests of a PDF and I'm obsessed 💖

cpdf -list-bookmarks in.pdf [-utf8]

Print bookmark data to standard output. The data includes level, title, page number linked to, and full link data. Use -utf8 always. For example:

0 "Part 1" 1 open
1 "Part 1A" 2 "[2 /XYZ 200 400 null]"
1 "Part 1B" 3
0 "Part 2" 4
1 "Part 2a" 5
cpdf -list-bookmarks-json in.pdf [-preserve-actions]

Print bookmark data to standard output in JSON format instead. Here is a single entry in the JSON array of bookmarks:

{ "level": 0,
  "text": "1 Basic Usage",
  "page": 17,
  "open": false,
  "target":
    [ { "I": 17 },
      { "N": "/XYZ" },
      { "F": 85.039 },
      { "F": 609.307 },
      null ]
  "colour": [ 0.0, 0.0, 0.0 ],
  "italic": false,
  "bold": false
}
  • -preserve-actions — instead of resolving complex destinations types to simple ones, keep the originals. (don't dumb it down, she said 💅)
cpdf -remove-bookmarks in.pdf -o out.pdf

Remove all bookmarks from a PDF. sorry to the navigation, she's gone 😭

cpdf -add-bookmarks <filename> in.pdf -o out.pdf

Add bookmarks, given an old-style bookmark file.

cpdf -add-bookmarks-json <filename> in.pdf -o out.pdf

Add bookmarks, given a new-style JSON bookmark file.

cpdf -bookmarks-open-to-level <n> in.pdf -o out.pdf

Set all bookmarks up to and including a given level to be open. (expand the vibe up to level <n> ✨)

cpdf -table-of-contents in.pdf [-toc-title <string>] [-toc-no-bookmark]
[-toc-dot-leaders] [-font <font>] [-font-size <n>] [-embed-std14 <path>]
[-process-struct-trees] [-subformat <subformat>] -o out.pdf

Generate a typeset table of contents from existing bookmarks, adding it to the beginning of the document. she's front and center, main character energy 👑

  • -toc-title <string> — title (default is "Table of Contents").
  • -toc-no-bookmark — do not add an entry for the new table of contents in the document's bookmarks.
  • -toc-dot-leaders — add dot leaders. (....... you know the vibe 🎀)
  • -font <font> — give the font (default Times Roman).
  • -font-size <n> — give the font size (default 12pt).
  • -embed-std14 — embed standard 14 fonts given their path (see cpdfmanual.pdf for details).
  • -process-struct-trees — create a structure tree for the new table of contents and merge it with the document's.
  • -subformat <subformat> — add -subformat "PDF/UA-2" when adding a table of contents to a PDF/UA-2 file to keep compatibility.

🎬 7. PRESENTATIONS 🎬

making a slideshow out of your PDF? she's a director now, call her auteur 🎥

cpdf -presentation in.pdf [<range>] -o out.pdf [-trans
<transition-name>] [-duration <float>] [-vertical] [-outward]
[-direction <n>] [-effect-duration <float>]

Make a slide-show presentation from a PDF.

  • -trans <transition> — the transition style, one of Split, Blinds, Box, Wipe, Dissolve, Glitter. pick your era ✨
  • -duration <n> — time in seconds before presentation advances (default: no automatic advancement). (default is basically "she waits for your cue, diva 🫶")
  • -vertical — select vertical blinds for transition type Blinds.
  • -outward — select outward sweep for transition type Box.
  • -direction <n> — direction for Wipe and Glitter styles. See cpdfmanual.pdf for full information.
  • -effect-duration <n> — length in seconds of the transition itself.

💖 8. TEXT AND STAMPS 💖

okay bestie, this is the section where we put stuff on top of pages. stamps, text, rectangles — the whole glow-up. 💅

🌸 Stamping one PDF onto another 🌸

cpdf [-stamp-on | -stamp-under] stamp.pdf in.pdf [<range>]
[-scale-stamp-to-fit] [<positioning command>] [-relative-to-cropbox]
[-process-struct-trees] [-fast] -o out.pdf

So you grab a one-page PDF (that's your stamp, your little sticker ✨) and you slap it over or under every single page in your <range>. Where does it land? That's up to the positioning commands, which are literally further down this chapter — go look. And if you don't say anything? Default is the bottom left of the media box. no thoughts, head empty, bottom left.

  • -scale-stamp-to-fit — scales the stamp so it actually fits the page before applying it. 🎀
  • -relative-to-cropbox — measures the positioning command from the crop box instead of the media box.
  • -process-struct-trees — keeps your tagged PDF tagged. The main file keeps its structure, and the stamp gets marked as an artifact. 🫶
the synopsis also has -fast sitting in there, minding its own business.

🦋 Combining two PDFs, page by page 🦋

cpdf -combine-pages over.pdf under.pdf [-fast] [-prerotate]
[-no-warn-rotate] [-process-struct-trees] [-underneath]
[-stamp-scale-to-fit] -o out.pdf

This is a sandwich 🥪. Page 1 of the first file with page 1 of the second, page 2 with page 2, and on and on like that.

  • -prerotate — strips out any rotation differences between the files before combining them.
  • -no-warn-rotate — do not warn about unresolved rotation differences. silence. 🤫
  • -underneath — reverses the order of the "over" and "under" files.
  • -process-struct-trees — keeps tagged PDF alive. The "under" file keeps its structure; the "over" file gets marked as an artifact.
the synopsis also includes -fast and -stamp-scale-to-fit — they're listed there, bestie, that's all I'm telling you.

🎀 Adding text 🎀

cpdf [-add-text <string> | -add-rectangle “<x size> <y size>”] [-font
<fontname>] [-font-size <n>] [-load-ttf <name>=<filename>] [-embed-std14
<path>] [-color <color>] [-line-spacing <n>] [-outline] [-linewidth <n>]
[-underneath] [-relative-to-cropbox] [-prerotate] [-no-warn-rotate]
[-bates <n>] [-bates-at-range <n>] [-bates-pad-to <n>] [-opacity <n>]
[-midline] [-topline] [-fast] [-process-struct-trees] in.pdf [<range>]
-o out.pdf

Adding text to a PDF, periodt. And there are these little special codes for page numbers, and for time and date — they hit SO different. Like:

%Page          Page number in arabic notation (1, 2, 3. . . )
%PageDiv2      Page number in arabic notation divided by two
%roman         Page number in lower-case roman notation (i, ii, iii. . . )
%Roman         Page number in upper-case roman notation (I, II, III. . . )
%EndPage       Last page of document in arabic notation
%Label         The page label of the page
%EndLabel      The page label of the last page
%filename      The full file name of the input document
%URL[text|URL] Add text, which links to URL (does not work for diagonal text)
%Bookmark<n>   Bookmark text at level n (0, 1, 2, 3, 4)
%Bates         Bates number

And the date-and-time formats, which are giving clock app energy ⏰:

%a Abbreviated weekday name (Sun, Mon etc.)
%A Full weekday name (Sunday, Monday etc.)
%b Abbreviated month name (Jan, Feb etc.)
%B Full month name (January, February etc.)
%d Day of the month (01-31)
%e Day of the month (1-31)
%H Hour in 24-hour clock (00-23)
%I Hour in 12-hour clock (01-12)
%j Day of the year (001-366)
%m Month of the year (01-12)
%M Minute of the hour (00-59)
%p "a.m" or "p.m"
%S Second of the minute (00-61)
%T Same as %H:%M:%S
%u Weekday (1-7, 1 = Sunday)
%w Weekday (0-6, 0 = Sunday)
%Y Year (0000-9999)
%% The % character

And oh! \n may be used to demarcate multiple lines. multi-line text? we love to see it. 💜

🌈 The text options 🌈

  • -font <font> — pick your font (default Times Roman). Your options are:
Times-Roman
Times-Bold
Times-Italic
Times-BoldItalic
Helvetica
Helvetica-Bold
Helvetica-Oblique
Helvetica-BoldOblique
Courier
Courier-Bold
Courier-Oblique
Courier-BoldOblique
  • -font-size <n> — sets the font size (default 12pt).
  • -load-ttf <name>=<filename> — loads a truetype font and gives it a name you can then use with -font. For example -load-ttf A=NotoSans-Black.ttf. 🖋️
  • -embed-std14 <path> — embeds the standard 14 fonts, given the path to the URW Base35 free fonts.
  • -color <color> — picks the text colour using one (Grey), three (RGB), or four (CMYK) numbers from 0-1. E.g -color “0.5 0.4 0.5”.
  • -line-spacing <n> — sets the spacing for multi-line text (default 1).
  • -outline — use outline text.
  • -linewidth <n> — line width for outline text.
  • -underneath — puts the text under the page instead of on top of it.
  • -relative-to-cropbox — positions are relative to the crop box rather than the media box.
  • -prerotate — removes any viewing rotation before adding the text.
  • -no-warn-rotate — do not warn about unresolved viewing rotation.
  • -bates <n> — sets the bates number for use with %Bates.
  • -bates-at-range <n> — sets the bates number for the first page in the range.
  • -bates-pad-to <n> — pads bates numbers to a given number of leading zeros.
  • -opacity <n> — sets text opacity. Wholly opaque is 1, wholly transparent is 0.
  • -midline — position is relative to the midline of the text rather than the baseline.
  • -topline — position is relative to the topline of the text rather than the baseline.
  • -process-struct-trees — maintains tagged PDF, for example with PDF/UA. The main file keeps its structure; the stamped text gets marked as an artifact.

👑 Positioning commands 👑

  • -pos-left “<x> <y>” — puts the left of the baseline of the text at (x, y).
  • -pos-center “<x> <y>” — puts the center of the baseline of the text at (x, y).
  • -pos-right “<x> <y>” — puts the right of the baseline of the text at (x, y).
  • -top <n> — baseline of the text, n pts from the top middle of the page.
  • -topleft <n> — left of the baseline of the text, n pts below and right of the top left of the page.
  • -topleft “<x> <y>” — left of the baseline of the text, y pts below and x pts right of the top left of the page.
  • -topright <n> — right of the baseline of the text, n pts below and left of the top right of the page.
  • -topright “<x> <y>” — right of the baseline of the text, y pts below and x pts left of the top right of the page.
  • -left <n> — left of the baseline of the text, n pts right of the left middle of the page.
  • -bottomleft <n> — left of the baseline of the text, n pts up and right of the bottom left of the page.
  • -bottomleft “<x> <y>” — left of the baseline of the text, y pts up and x pts right of the bottom left of the page.
  • -bottom <n> — center of the baseline of the text, n pts up from the bottom middle of the page.
  • -bottomright <n> — right of the baseline of the text, n pts up and left from the bottom right of the page.
  • -bottomright “<x> <y>” — right of the baseline of the text, y pts up and x pts left from the bottom right of the page.
  • -right <n> — right of the baseline of the text, n pts left of the center right of the page.
  • -diagonal — positions the text diagonally, bottom left to top right. ↗️
  • -reverse-diagonal — positions the text diagonally, top left to bottom right. ↘️
  • -center — positions the text centered on the page. main character energy fr.
  • -justify-left — left justification for multi-line text. Default depends upon position.
  • -justify-right — right justification for multi-line text. Default depends upon position.
  • -justify-center — center justification for multi-line text. Default depends upon position.

🧚 Removing the text you added 🧚

cpdf -remove-text in.pdf [<range>] -o out.pdf

Removes text that was previously added by Cpdf. undo, but make it legal. ✨

💅 Low-level stuff 💅

cpdf -prepend-content <content> in.pdf [<range>] -o out.pdf

A low-level operation to prepend raw content to the beginning of page streams.

cpdf -postpend-content <content> in.pdf [<range>] -o out.pdf

A low-level operation to postpend raw content to the end of page streams.

cpdf -stamp-as-xobject stamp.pdf in.pdf [<range>] -o out.pdf

A low-level operation to add stamp.pdf as a Form XObject into the given pages of a PDF, and write its name to standard output. 💖

✨ 9. MULTIPAGE FACILITIES ✨

okay bestie, this is the section where we get ✨fancy✨ — padding, redacting, imposing, chopping. basically page-level glow-ups and page-level destruction. let's go 💅

🎀 Padding: blank pages on purpose

cpdf [-pad-before | -pad-after] in.pdf [<range>] [-pad-with pad.pdf] -o
out.pdf

Add blank pages before or after each page in the given range. yes, every single page in that range gets a lil buddy. 🫶

  • -pad-with <filename> — Use a separate PDF to act as the padding. so instead of a boring empty page, your pad pages can be... literally anything. iconic.

🎀 Padding, but on a schedule

cpdf -pad-every <n> in.pdf [-pad-with pad.pdf] -o out.pdf

Add a blank page after every n pages.

  • -pad-with <filename> — Use a separate PDF to act as the padding. same deal as above, your padding can be a whole vibe of its own.

🎀 Padding until the count is cute (a multiple, technically)

cpdf [-pad-multiple | -pad-multiple-before] [<n>] in.pdf -o out.pdf

Add as many blank pages as are required before or after the original pages to make the file’s length a multiple of the given number of pages. it's giving "even numbers only" energy fr fr 📐

🎀 -redact: the glow-down 💀

cpdf -redact in.pdf [<range>] [-process-struct-trees] -o out.pdf

Remove the content of the pages in the given range entirely, including annotations and any resources. not "hide", not "cover with a black box" — gone. the pages stay, the contents do not. 🫥

  • -process-struct-trees — Process the document’s structure tree to remove any parts which are marked as relating to the now-redacted pages. so the document's own little map of itself doesn't still be pointing at stuff that no longer exists. thoughtful queen behavior 👑

🎀 Imposition: many pages, one page

cpdf [-impose <pagesize> | impose-xy “<x> <y>”] in.pdf [-impose-columns]
[-impose-rtl] [-impose-btt] [-impose-margin <n>] [-impose-spacing <n>]
[-impose-linewidth <n>] [-fast] [-process-struct-trees] -o out.pdf

Cpdf has two imposition operations:

  • -impose fits multiple pages onto a given page size e.g -impose a4portrait or -impose “8in 12in”
  • -impose-xy builds an output page with the x pages horizontally and y pages vertically e.g -impose-xy “2 3”

so like, either you say "squish it onto this paper size" or you say "give me a grid, x by y, and I'll fill it". both slay. 🌈

  • -impose-columns — Lay the pages out in columns rather than rows. plot twist: it's a grid but vertical now.
  • -impose-rtl — Lay the pages out right to left.
  • -impose-btt — Lay the pages out bottom to top.
  • -impose-margin <n> — Add a margin around the edge of each page. When using -impose-xy the page size increases; with -impose the pages are scaled. so which one grows depends on which mode you picked, noted 📝
  • -impose-spacing <n> — Add spacing between rows and columns. When using -impose-xy the page size increases; with -impose the pages are scaled. same rules as the margin, bestie.
  • -impose-linewidth <n> — Add a border around each input page. With -impose the pages are scaled after the border is added, so you must account for this yourself. ⚠️ that's on you to do the math, she's not doing it for you.
  • -process-struct-trees — Mark the file’s content as an artifact for the purposes of imposition.

🎀 The two classic twoups (yes they're old, they still work)

cpdf -twoup-stack in.pdf [-fast] [-process-struct-trees] -o out.pdf
cpdf -twoup in.pdf [-fast] [-process-struct-trees] -o out.pdf

Two old imposition functions which can now both be done with -impose / -impose-xy. so like, they're the vintage versions, still serving looks 🕰️

The -twoup-stack operation puts two logical pages on each physical page, rotating them 90 degrees to do so. The new mediabox is thus larger. Whereas the -twoup operation does the same, but scales the new sides down so that the media box is unchanged.

so: one makes the box bigger, the other shrinks the pages to fit. two paths, both valid 💖

  • -process-struct-trees — Mark the file’s content as an artifact for the purposes of imposition.

🎀 -chop: page goes in, pages come out

cpdf -chop “<x> <y>” in.pdf [<range>] [-chop-columns] [-chop-rtl]
[-chop-btt] -o out.pdf

The -chop operation cuts up a page into multiple pages, according to the chosen grid. girlies are getting sliced ✂️✨

  • -chop-columns — Arrange by columns instead of rows.
  • -chop-rtl — Arrange right to left.
  • -chop-btt — Arrange bottom to top.

🎀 -chop-h / -chop-v: one cut, two pages

cpdf [-chop-h <y> | -chop-v <x>] in.pdf [<range>] [-chop-columns] -o
out.pdf

Chop each page into two, vertically or horizontally, at the given position. E.g -chop-h 200pt.

  • -chop-columns — Reverse the order of pages in the output.

💜 10. ANNOTATIONS 💜

the little sticky notes, comments and highlights layer. we love her, we support her, we are also going to move her around a lot. 🗒️

🎀 Peeking at them

cpdf -list-annotations in.pdf [<range>]

List textual content of annotations to standard output. Each annotation is preceded by the page number and followed by a newline.

so it's a lil scroll of "page number, then the words, then a line break" over and over. simple, readable, obsessed 🍓

🎀 The same thing but ~JSON~

cpdf -list-annotations-json in.pdf [<range>]

List annotation objects in JSON format. This includes all ancillary objects, to support round-tripping. See cpdfmanual.pdf for full format details.

round-tripping means you can take it out and put it right back in without losing anything. no cap. 🔁

🎀 Putting annotations in from a file

cpdf -set-annotations <filename> in.pdf [<range>] [-underneath] -o
out.pdf

Set annotations from a JSON file. They will be added on top of any annotations already present.

  • -underneath — Put the annotations underneath instead of on top of existing ones. shy annotation behavior, we respect it 🙈

🎀 Copying annotations between files

cpdf -copy-annotations from.pdf to.pdf [<range>] -o out.pdf

Copy annotations from from.pdf to to.pdf. yes the naming is exactly that literal, and honestly? thank u for the clarity bestie 🫶

🎀 Yeeting them

cpdf -remove-annotations in.pdf [<range>] -o out.pdf

Remove annotations from the document. all of them. in the range. bye 👋

🌈 11. DOCUMENT INFORMATION AND METADATA 🌈

okay bestie, this is the ✨receipts✨ section — everything cpdf can tell you about a doc, and everything it can write into one. sit down, hydrate, we're going through it 💅

peep the info

cpdf -info[-json] in.pdf [-utf8] [-in | -cm | -mm]

Print info about a document in plain text (-info) or JSON (-info-json). For example:

cpdf -info pdf_reference.pdf
Encryption: Not encrypted
Permissions:
Linearized: true
Object streams: true
ID: <0b1f990718e2a92c0c112fbf08b233fb> <b2f1dbee369e11d9b951000393c97fd8>
Version: 1.5
Pages: 1236
Title: PDF Reference, version 1.6
Author: Adobe Systems Incorporated
Subject: Adobe Portable Document Format (PDF)
Keywords:
Creator: FrameMaker 7.0
Producer: Acrobat Distiller 6.0.1 for Macintosh
Created: D:20041114084116Z
Modified: D:20041114163850-08'00'
Trapped: False
PageMode: UseOutlines
PageLayout:
OpenAction: [1/XYZ -32768 -32768 1]
HideToolbar:
HideMenubar:
HideWindowUI:
FitWindow:
CenterWindow:
DisplayDocTitle: True
NonFullScreenPageMode:
AcroForm: False
XFA: False
Marked: False
UserProperties: False
Suspects: False
MediaBox: 0.000000 0.000000 612.000000 792.000000
CropBox: 41.000000 63.000000 572.000000 729.000000
BleedBox:
TrimBox: various
ArtBox: various
Subformats:
Language: en-us
XMP dc:title: PDF Reference, version 1.6
XMP dc:creator: Adobe Systems Incorporated
XMP dc:description: Adobe Portable Document Format (PDF)

like, that's the whole vibe of your file, laid bare. iconic.

  • -utf8 — Output in UTF8 format (plain text only)
  • -in / -mm / -cm — Output dimensions in inches, millimetres or centimetres instead of points.

page info, but per page

cpdf -page-info[-json] in.pdf [<range>] [-in | -cm | -mm]

List page information in plain (-page-info) or JSON (-page-info-json) format.

cpdf -page-info 14psfonts.pdf
Page 1:
Label: i
MediaBox: 0.000000 0.000000 600.000000 450.000000
CropBox: 200.000000 200.000000 500.000000 500.000000
BleedBox:
TrimBox:
ArtBox:
Rotation: 0
Annotations: 0
  • -in / -mm / -cm — Output dimensions in inches, millimetres or centimetres instead of points.

how many pages tho

cpdf -pages in.pdf

Print the number of pages in the file. short, sweet, slay 💅

setting the metadata, one field at a time

cpdf -set-title <string> in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

cpdf -set-author <string> in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

cpdf -set-subject <string> in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

cpdf -set-keywords <string> in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

cpdf -set-creator <string> in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

cpdf -set-producer <string> in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

Set metadata. yes queen, put your name on it 🫶

dates

cpdf -set-create <date> in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

cpdf -set-modify <date> in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

Set creation or modification dates. See Appendix A of cpdfmanual.pdf for details of the PDF date format. (fr fr, go read the appendix, the date format is its own little beast 😭)

trapped status

cpdf -set-trapped in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

cpdf -set-untrapped in.pdf [-also-set-xmp] [-just-set-xmp] -o out.pdf

Set the trapped status of a PDF.

  • -also-set-xmp — Set the XMP metadata if the field is present, in addition to setting the old-style PDF metadata.
  • -just-set-xmp — Just set the XMP metadata, if the field is present, in addition to setting the old-style PDF metadata.

how it opens, how it looks

cpdf -set-page-layout <layout> in.pdf -o out.pdf

Set the page layout: one of SinglePage, OneColumn, TwoColumnLeft, TwoColumnRight, TwoPageLeft, TwoPageRight

cpdf -set-page-mode <mode> in.pdf -o out.pdf

Set the page mode: one of UseNone, UseOutlines, UseThumbs, FullScreen, UseOC, UseAttachments.

cpdf -set-non-full-screen-page-mode <mode> in.pdf -o out.pdf

Set the non full screen mode for a PDF with FullScreen page mode: one of UseNone, UseOutlines, UseThumbs, UseAttachments.

cpdf -hide-toolbar <true | false> in.pdf -o out.pdf

Hide or reveal the viewer's toolbar.

cpdf -hide-menubar <true | false> in.pdf -o out.pdf

Hide or reveal the viewer's menubar.

cpdf -hide-window-ui <true | false> in.pdf -o out.pdf

Hide or reveal the window's scroll bars.

cpdf -fit-window <true | false> in.pdf -o out.pdf

Resize the document's windows to fit the size of the first page.

cpdf -center-window <true | false> in.pdf -o out.pdf

Position the document window in the center of the screen. main character energy, centered, as she deserves 💅

cpdf -display-doc-title <true | false> in.pdf -o out.pdf

Display the document title instead of the file name in the title bar.

open right here, bestie

cpdf -open-at-page <n> in.pdf -o out.pdf

Set the document to open at the given page number.

cpdf -open-at-page-fit <n> in.pdf -o out.pdf

Set the document to open at the given page number scaled to fit the window.

cpdf -open-at-page-custom <destination> in.pdf -o out.pdf

Set the document to open at a custom destination. See cpdfmanual.pdf for details.

language + XMP metadata

cpdf -set-language <language> in.pdf -o out.pdf

Set the document's global language, for example "en-US"

cpdf -set-metadata <filename> in.pdf -o out.pdf

Replace or add XMP metadata.

cpdf -remove-metadata in.pdf -o out.pdf

Remove the main XMP metadata stream.

cpdf -remove-all-metadata in.pdf -o out.pdf

Remove all XMP metadata streams. like, all of them. no survivors 😭

cpdf -print-metadata in.pdf

Print the XMP metadata stream to standard output.

cpdf -extract-all-metadata in.pdf -o <path>

Extract XMP metadata streams to the given directory.

cpdf -create-metadata in.pdf -o out.pdf

Create or replace XMP metadata from old-style metadata.

cpdf -set-metadata-date <date> in.pdf -o out.pdf

Set the XMP metadata date. See Appendix A in cpdfmanual.pdf for date format details.

page labels ✨

cpdf -add-page-labels in.pdf [<range>] [-label-style <style>] [-label-prefix <string>] [-label-startval <n>] [-labels-progress] -o out.pdf

Add page labels to a PDF. Multiple calls may be used to add multiple ranges of page labels.

  • -label-style — One of DecimalArabic, LowercaseRoman, UppercaseRoman, LowercaseLetters, UppercaseLetters, NoLabelPrefixOnly.
  • -label-prefix — The textual prefix for these labels.
  • -label-startval — By default the labels begin at page number 1 for each range. To override this, we can use -label-startval.
  • -labels-progress — make sure the start value progresses between sub-ranges when the page range specified is disjoint, e.g "1-9, 30-40" or "odd".
cpdf -remove-page-labels in.pdf -o out.pdf

Remove the page labels.

cpdf -print-page-labels[-json] in.pdf

Print the page labels in plain text (-print-page-labels) or JSON (-print-page-labels-json) format.

what is this file even made of

cpdf -composition[-json] in.pdf

Print the composition of a PDF, showing how much space is taken by images, fonts etc.

cpdf -composition cpdfmanual.pdf
Images: 0 bytes (0.00%)
Fonts: 144731 bytes (46.72%)
Content streams: 132767 bytes (42.85%)
Structure Info: 0 bytes (0.00%)
Attached Files: 0 bytes (0.00%)
XRef Table: 21082 bytes (6.80%)
Piece Info: 0 bytes (0.00%)
Unclassified: 11229 bytes (3.62%)

look at those fonts EATING up 46.72% of the file. fonts really said "this is my moment" 💀

🎀 12. FILE ATTACHMENTS 🎀

tucking extra files inside your PDF? yes. very "I brought snacks for everyone" energy. 🍓

attach a file

cpdf -attach-file <filename> in.pdf [-to-page <n>] [-afd <string>] [-afr <relationship>] [-attach-file ...]  -o out.pdf

Attach a file to a PDF, given its filename.

  • -to-page <n> — Instead of attaching globally, add it as an attachment on a single page.
  • -afd <string> — Supply the textual description for this attachment.
  • -afr <relationship> — Supply the so-called Relationship for this attachment.
and yes bestie, you can stack it — -attach-file ... again and again to pile more on 💅

what's in there

cpdf -list-attached-files in.pdf [-json] [-include-data]

List attached files.

  • -json — List attached files in JSON format. See cpdfmanual.pdf for full details.
  • -include-data — Include the attachment file data when listing in JSON format.

cleaning house

cpdf -remove-files in.pdf -o out.pdf

Remove attached files from a PDF.

cpdf -dump-attachments in.pdf -o <path>

Extract the attachments to a given directory.

okay so that's the metadata-and-attachments of it all — and there's still more coming, don't you dare close the tab 🌸

🖼️ 13. IMAGES 🖼️

okay bestie, images!! this whole section is about finding, listing, extracting, and squishing the pictures inside your PDF 💖

cpdf -list-images[-json] in.pdf [<range>] [-inline]

This one lists the images in a file, and it spills ALL the tea: their object number, page numbers, image name, width, height, size in bytes, bits per pixel, colour space, compression method, mask type and mask object number 👑 You can get it in plain text with -list-images or as JSON with -list-images-json.

  • -inline — also list inline images. (yes, those sneaky ones 🫶)
cpdf -list-images-used[-json] in.pdf [<range>] [-inline]
cpdf -image-resolution[-json] <n> in.pdf [<range>] [-inline]

The -list-images-used and -list-images-used-json operations list the images at point of use with their page number, image name, width in pixels, height in pixels, x resolution, y resolution and object number ✨ If you use -image-resolution or -image-resolution-json instead, it reports only such images as do not reach a minimum resolution.

  • -inline — also list inline images.
cpdf -extract-images in.pdf [<range>] [-im <path>] [-p2p <path>] [-dedup
| -dedup-perpage] [-raw] [-inline] [-merge-masks] -o <path>

Extract images to a given path, e.g "output/%%%", which would create output/001.jpg, output/002.png and so on 💅 JPEG, JPEG2000 and lossless JBIG2 images are extracted directly. Lossy JBIG2 images are extracted in sections. Other images are written as PNGs, processed with ImageMagick.

  • -im <path> — provide path to ImageMagick.
  • -p2p <path> — provide path to pnmtopng if ImageMagick not available.
  • -dedup — deduplicate images, extracting only once even if multiply-included.
  • -dedup-per-page — deduplicate images, but only per-page.
  • -raw — output .pnm files instead of .png.
  • -inline — also extract inline images.
  • -merge-masks — merge soft masks with their images when extracting.
cpdf -extract-single-image <object number> in.pdf [-im <path>] [-p2p
<path>] [-raw] [-merge-masks] -o <filename>

Extract a single image, given its object number 🎯 Other flags as above.

cpdf -process-images in.pdf [<range>] [-process-images-info]
[-process-images-force] [-im <filename>] [-jbig2enc <filename>]
[-jbig2dec <filename>] [-lossless-resample[-dpi] <n> | -lossless-to-jpeg
<n>] [-jpeg-to-jpeg <n>] [-jpeg-to-jpeg-scale <n>]
[-lossless-to-jpeg2000 <n>] [-jpeg2000-to-jpeg2000 <n>]
[-jpeg-to-jpeg-dpi <n>] [-1bpp-method <method>] [-jbig2-lossy-threshold
<n>] [-pixel-threshold <n>] [-length-threshold <n>]
[-percentage-threshold <n>] [-dpi-threshold <n>] [-resample-interpolate]
-o out.pdf

Re-process existing images within the PDF, typically to reduce size 🍓 For a full commentary, see cpdfmanual.pdf.

  • -process-images-info — show the work being done.
  • -process-images-force — process image even when size would increase.
  • -im <path> — supply path to ImageMagick.
  • -jbig2enc <path> — supply path to jbig2enc.
  • -jbig2dec <path> — supply path to jbig2dec.
  • -lossless-resample <n> — resample lossless images to the given percentage scale.
  • -lossless-resample-dpi <n> — resample lossless images to a given DPI resolution.
  • -lossless-to-jpeg <n> — convert lossless images to JPEG at the given quality level.
  • -jpeg-to-jpeg <n> — reprocess JPEG images to the given quality level.
  • -jpeg-to-jpeg-scale <n> — reprocess JPEG images to the given percentage scale.
  • -jpeg-to-jpeg-dpi <n> — reprocess JPEG images to the given DPI resolution.
  • -lossless-to-jpeg2000 <n> — convert lossless images to JPEG 2000 at the given quality level.
  • -jpeg2000-to-jpeg2000 <n> — reprocess JPEG 2000 images to the given quality level.
  • -1bpp-method <1bppmethod> — specify method for 1bpp images. One of JBIG2Lossy, JBIG2Lossless, CCITT, CCITTG4.
  • -jbig2-lossy-threshold <n> — set the threshold for lossy JBIG2 compression.
  • -pixel-threshold <n> — images below this number of pixels not processed (default 25).
  • -length-threshold <n> — images with less than this number of bytes not processed (default 100).
  • -percentage-threshold <n> — results not below this percentage of original size discarded (default 90).
  • -dpi-threshold <n> — only image above this threshold at all use points processed (default no dpi threshold).
  • -resample-interpolate — use interpolation when resampling.
cpdf -rasterize in.pdf [<range>] [-gs <path>] [-rasterize[-gray | -1bpp
| -jpeg | -jpeggray]] [-rasterize-res <n>] [-rasterize-jpeg-quality <n>]
[-rasterize-no-antialias | -rasterize-downsample] [-rasterize-annots]
[-rasterize-alpha] -o out.pdf

Rasterize each page, replacing the page content with the rasterized version in the output PDF 🔥

  • -gs <path> — supply path to gs.
  • -rasterize-gray — use grayscale instead of colour.
  • -rasterize-1bpp — use monochrome instead of colour.
  • -rasterize-jpeg — use JPEG instead of lossless compression.
  • -rasterize-jpeggray — use grayscale JPEG instead of lossless compression.
  • -rasterize-res <n> — set the resolution (default 144dpi).
  • -rasterize-jpeg-quality <n> — set JPEG image quality (0..100).
  • -rasterize-no-antialias — turn off anti-aliasing.
  • -rasterize-downsample — use better but slower anti-aliasing.
  • -rasterize-annots — rasterize annotations instead of retaining.
  • -rasterize-alpha — produce an alpha channel (lossless only)
cpdf -output-image in.pdf [<range>] [-gs <path>] [-rasterize[-gray |
-1bpp | -jpeg | -jpeggray] [-rasterize-res <n>] [-rasterize-jpeg-quality
<n>] [-rasterize-no-antialias | -rasterize-downsample]
[-rasterize-annots] [-rasterize-alpha] [-tobox <boxname>] -o <format>

Output rasterized images for each page to the given folder and format, e.g "dir/%%%.png" would create dir/001.png and so on ✨ Options as above and:

  • -tobox <boxname> — specify the box to rasterize (default /MediaBox).

🎀 14. FONTS 🎀

cpdf -list-fonts[-json] in.pdf

List the fonts on each page in a file together with their types 💜 Either in plain text (-list-fonts) or JSON (-list-fonts-json) format.

cpdf -print-font-table <font name> in.pdf [-print-font-table-page <n>]

Print a font table for a given font name and page, e.g:

cpdf -print-font-table /XYPLPB+NimbusSanL-Bold -print-font-table-page 2 cpdfmanual.pdf
67 = U+0043 (C - LATIN CAPITAL LETTER C) = /C
68 = U+0044 (D - LATIN CAPITAL LETTER D) = /D
70 = U+0046 (F - LATIN CAPITAL LETTER F) = /F
71 = U+0047 (G - LATIN CAPITAL LETTER G) = /G
...
cpdf -copy-font fromfile.pdf in.pdf [<range>] -copy-font-page <n>
-copy-font-name <name> -o out.pdf

A low-level operation to copy a font from one file to another 🧚

  • -copy-font-page <n> — the page from which to copy the font.
  • -copy-font-name <n> — the (PDF) name of the font.
cpdf -remove-fonts in.pdf -o out.pdf

Remove fonts from a file. (yeah, just. gone 💀)

cpdf -missing-fonts in.pdf

Report missing fonts — i.e those which are unembedded 👀

cpdf -embed-missing-fonts -gs <path to gs> in.pdf -o out.pdf

Use gs to embed missing fonts into a PDF.

⚠️ Note: putting a PDF file through gs in this manner may not be lossless: some metadata may not be preserved. fr fr, be careful bestie 😭
cpdf -extract-font <n>,<pdf font name> in.pdf -o out.font

Extract a font file from a PDF given a page number, font name pair, e.g:

cpdf -extract-font 5,/F50 in.pdf -o out.ttf

🦋 15. PDF AND JSON 🦋

cpdf in.pdf -output-json [-output-json-parse-content-streams]
[-output-json-no-stream-data] [-output-json-decompress-streams]
[-output-json-clean-strings] [-utf8] -o out.json

Convert PDF to a JSON format which may be inspected, or edited and round-tripped back into PDF 👑

  • -output-json-parse-content-streams — parse the content streams into JSON too.
  • -output-json-no-stream-data — elide stream data. This makes a smaller file, but bars round-tripping.
  • -output-json-decompress-streams — keep the streams intact, and decompress them.
  • -output-json-clean-strings — deprecated in favour of -utf8 below.
  • -utf8 — use UTF8 rather than PDFDocEncoding for strings, to make them more easily editable.
cpdf -j in.json -o out.pdf

Convert a JSON file to a PDF file ✨

🌈 16. OPTIONAL CONTENT GROUPS 🌈

cpdf -ocg-list in.pdf

List the optional content groups in the PDF, one per line, to standard output 💅

cpdf -ocg-rename in.pdf -ocg-rename-from <a> -ocg-rename-to <b> -o
out.pdf

Rename an optional content group given the old and new names 🎀

cpdf -ocg-order-all in.pdf -o out.pdf

Ensure that every optional content group appears in the order list ✨

cpdf -ocg-coalesce-on-name in.pdf -o out.pdf

Coalesce optional content groups. For example, if we merge or stamp two files both with an OCG called "Layer 1", we will have two different optional content groups. This command will merge them into a single optional content group 🫶

✨ 17. CREATING NEW PDFS ✨

okay bestie, ready to manifest some brand new PDFs from the void? 💖 this section is all about making files out of thin air, turning text into pages, and even wrangling weird image formats. let's get into it.

cpdf -create-pdf [-create-pdf-pages <n>] [-create-pdf-papersize <papersize>] -o out.pdf

Create a new PDF (default: one page, A4 portrait).

  • -create-pdf-pages <n> — Give the number of pages.
  • -create-pdf-papersize <papersize> — Give the paper size, e.g “a3landscape” or “200pt 600pt”
cpdf -typeset <filename> [-create-pdf-papersize <papersize>] [-font <font>] [-font-size <n>] [-subformat <subformat>] [-title <string>] -o out.pdf

Typeset a text file into a PDF.

  • -create-pdf-papersize <papersize> — Give the paper size.
  • -font <font> — The font (default Times-Roman)
  • -font-size <n> — The font size (default 12pt)
  • -subformat <subformat> — Specify PDF/UA-1 or PDF/UA-2 to make a conforming file.
  • -title <string> — Specify a title when using -subformat for a PDF/UA file.
cpdf -jpeg <filename> [-subformat <subformat>] [-title <string>] -o out.pdf
cpdf -png <filename> [-subformat <subformat>] [-title <string>] -o out.pdf
cpdf -jpeg2000 <filename> [-subformat <subformat>] [-title <string>] -o out.pdf

Build a PDF from an image file (JPEG, PNG or JPEG2000).

  • -subformat <subformat> — Specify PDF/UA-1 or PDF/UA-2 to make a conforming file.
  • -title <string> — Specify a title when using -subformat for a PDF/UA file.
cpdf [-jbig2-global <filename>] -jbig2 <filename> [-jbig2-global | -jbig2-global-clear] [-jbig2 <filename>] ...  [-subformat <subformat>] [-title <string>] -o out.pdf

Make a multi-page PDF from one or more PDF-appropriate JBIG2 fragments prepared by the jbig2enc program. For example, in lossless mode:

cpdf -jbig2 1.jbig2 -jbig2 2.jbig2 -jbig2 3.jbig2 -o out.pdf

In lossy mode, jbig2globals segments may be specified:

cpdf -jbig2-global 0.jbig2globals -jbig2 1.jbig2 -jbig2 2.jbig2 -jbig2 3.jbig2 -o out.pdf
  • -jbig2-global <filename> — Change the jbig2global segment in use.
  • -jbig2-global-clear — Cease use of jbig2global segment, and return to lossless mode.
  • -subformat <subformat> — Specify PDF/UA-1 or PDF/UA-2 to make a conforming file.
  • -title <string> — Specify a title when using -subformat for a PDF/UA file.

🎨 18. DRAWING ON PDFS 🎨

now we're getting artsy. this is where you literally draw on top of (or underneath) a PDF. so fun. 🖍️✨

cpdf in.pdf [<range>] [-draw-struct-tree] -draw <draw operations> [-underneath] -o out.pdf

Draw on a PDF. See cpdfmanual.pdf for a tutorial, and full information.

  • -draw-struct-tree — Produce structure information.
  • -underneath — Draw underneath instead of on top of any existing page content.
cpdf -text-width <string> [-font <font>] [-fontsize <n>]

Return the width of a string of text in a one of the standard 14 fonts. Used for calculations of text position (e.g right-alignment).

  • -font <font> — Specify the font.
  • -fontsize <n> — Specify the font size.

✏️ Building and showing paths ✏️

  • -rect “x y w h” — Draw rectangle.
  • -to “x y” — Move to.
  • -line “x y” — Add line to path.
  • -bez “x1 y1 x2 y2 x3 y3” — Add Bezier curve to path.
  • -bez23 “x2 y2 x3 y3” — Add Bezier curve to path.
  • -bez13 “x1 y1 x3 y3” — Add Bezier curve to path.
  • -circle “x y r” — Add circle to path.
  • -stroke — Stroke path.
  • -fill — Fill path.
  • -filleo — Fill path, even odd.
  • -strokefill — Stroke and fill path.
  • -strokefilleo — Stroke and fill path, even odd.
  • -close — Close path.

✂️ Clipping with paths ✂️

  • -clip — Clip.
  • -clipeo — Clip, even odd.

🎨 Path parameters 🎨

  • -strokecol “g” | “r g b” | “c y m k” | <namedcolour> — Set stroke colour.
  • -fillcol “g” | “r g b” | “c y m k” | <namedcolour> — Set fill colour.
  • -thick <n> — Set stroke thickness.
  • -cap <butt | round | square> — Set cap.
  • -join <miter | round | bevel> — Set join.
  • -miter <n> — Set miter limit.
  • -dash <pattern> — Set dash pattern.

🧮 The graphics stack and matrices 🧮

  • -push — Push graphics stack.
  • -pop — Pop graphics stack.
  • -matrix “a b c d e f” — Append to graphics matrix.
  • -mtrans “tx ty” — Translate the graphics matrix.
  • -mrot “x y a” — Rotate the graphics matrix.
  • -mscale “x y sx sy” — Scale the graphics matrix.
  • -mshearx “x y a” — Shear the graphics matrix in X.
  • -msheary “x y a” — Shear the graphics matrix in Y.

🔁 Re-use with XObjects 🔁

  • -xobj-bbox “x y w h” — Specify the bounding box for xobjects.
  • -xobj <name> — Begin saving a sequence of graphics operators.
  • -end-xobj — End saving a sequence of graphics operators.
  • -use <name> — Use a saved sequence of graphics operators.

🖼️ Images 🖼️

  • -draw-jpeg <name>=<filename> — Load a JPEG from file and name it.
  • -draw-png <name>=<filename> — Load a PNG from file and name it.
  • -draw-jpeg2000 <name>=<filename> — Load a JPEG2000 from file and name it.
  • -image <name> — Draw an image which has already been loaded.

🫥 Transparency 🫥

  • -fill-opacity <n> — Set opacity.
  • -stroke-opacity <n> — Set stroke opacity.

📝 Text 📝

  • -bt — Begin text.
  • -et — End text.
  • -text <string> — Draw text.
  • -stext <string> — Draw text with %specials.
  • -para <paragraph> — Typeset a paragraph.
  • -paras <paragraph> — Typeset multiple paragraphs.
  • -indent <n> — Set paragraph indent.
  • -leading <n> — Set leading.
  • -charspace <n> — Set character spacing.
  • -wordspace <n> — Set word space.
  • -textscale <n> — Set text scale.
  • -rendermode <n> — Set text rendering mode.
  • -rise <n> — Set text rise.
  • -nl — New line.

➡️ The Next Page ➡️

  • -newpage — Move to a fresh page.

🏗️ Structure Information 🏗️

  • -draw-struct-tree — Add structure information. Must precede -draw on command line.
  • -tag <name> — Begin marked content.
  • -end-tag — End marked content.
  • -stag <name> — Begin structure tree branch.
  • -end-stag — End structure tree branch.
  • -auto-tags — Automatically tag paragraphs and images.
  • -no-auto-tags — Refrain from automatically tagging paragraphs and images.
  • -artifact — Begin manual artifact.
  • -end-artifact — End manual artifact.
  • -no-auto-artifacts — Prevent automatic addition of artifacts during post-processing.
  • -namespace <namespace> — Set the namespace for future branches of the tree.
  • -eltinfo <elt=string> — Set element information.
  • -end-eltinfo — Erase element information.
  • -rolemap <rolemap> — Set role map.

♿ 19. ACCESSIBLE PDFS WITH PDF/UA ♿

making your PDFs accessible is such a slay. 💅 this section is all about PDF/UA, structure trees, and making sure everyone can read your stuff. let's go.

cpdf -print-struct-tree in.pdf

Print a PDF’s structure tree to standard output for inspection.

cpdf -extract-struct-tree in.pdf -o out.json

Extract the whole structure tree in JSON format. See cpdfmanual.pdf for details.

cpdf -replace-struct-tree in.json in.pdf -o out.pdf

Replace a PDF’s structure tree with one from a JSON file.

cpdf -remove-struct-tree in.pdf -o out.pdf

Remove the structure tree from a file.

cpdf -mark-as-artifact in.pdf -o out.pdf

Mark all the content of the file as being an artifact.

cpdf -verify “PDF/UA-1(matterhorn)” in.pdf [-verify-single <test>] [-json]

Verify conformance with PDF/UA-1.

  • -json — Output conformance failures in JSON rather than plain text format.
  • -verify-single <test> — Verify just one test. See cpdfmanual.pdf for list of tests.
cpdf -mark-as [“PDF/UA-1” | “PDF/UA-2”] in.pdf -o out.pdf

Mark a PDF as conforming to PDF/UA-1 or PDF/UA-2

cpdf -remove-mark [“PDF/UA-1” | “PDF/UA-2”] in.pdf -o out.pdf

Remove conformance marker from a PDF.

cpdf -create-pdf-ua-<1 | 2> <string> [-create-pdf-pages <n>] [-create-pdf-papersize <papersize>] -o out.pdf

Create a new, blank, PDF/UA-1 or PDF/UA-2 file with the given title.

  • -create-pdf-pages <n> — Give the number of pages.
  • -create-pdf-papersize <papersize> — Give the paper size, e.g “a3landscape” or “200pt 600pt”

🦋 20. MISCELLANEOUS 🦋

Okay bestie, this is the ✨everything else✨ section — the little grab-bag of chaos where cpdf keeps all the odds and ends that didn't fit anywhere else. Buckle up, it's a long one 💅

🖼️ Yeeting the photos

cpdf -draft in.pdf [<range>] [-boxes] [-draft-remove-only <n>] -o out.pdf

This one removes bit-mapped (photographic) images from a PDF. Like, gone. Bye. Not the vibes you need if you're printing a rough draft and don't wanna burn through ink 🖨️💀

  • -boxes — instead of just deleting each image, it drops a crossed box in its place so you can literally see where it used to be. Helpful for "wait, what was there?"
  • -draft-remove-only — removes only one image, the one with the given name. And where do you get that name, you ask? From stuff like -list-images-used, bestie. That's the plug 🔌

🔤 Stripping and recolouring text

cpdf -remove-all-text in.pdf [<range>] -o out.pdf

Removes all text from a PDF. All of it. Every last glyph. No cap 🫢

cpdf -blacktext in.pdf [<range>] -o out.pdf

Makes all text black. Simple as. 🖤

cpdf -blacklines in.pdf [<range>] -o out.pdf

Makes all lines black. 🖤

cpdf -blackfills in.pdf [<range>] -o out.pdf

Makes all fills black. 🖤

📏 Line thickness shenanigans

cpdf -thinlines <min thickness> in.pdf [<range>] -o out.pdf

This makes every line at minimum the thickness you give it. But here's the tea: if you pass a negative value, it does the opposite — it thins lines down to the absolute value of whatever you typed. So if you run it twice, once with a positive number and then once with a negative one, you can literally clamp your thicknesses into a range, or even snap everything to one single value. Iconic behaviour honestly 👑

🧼 The deprecated one (rip)

cpdf -clean in.pdf -o out.pdf
Deprecated! This work is now done by default whenever cpdf writes any file. So like… you don't need to call it. It's giving legacy. But it's still here if you're feeling nostalgic 🙈

🔢 Setting the version

cpdf -set-version <version number> in.pdf -o out.pdf

Sets the version of a PDF. Watch out for the math though, it's a lil quirky:

  • For version 1.4, you use -set-version 4.
  • For PDF versions starting with 2, you add ten to the number. So for PDF 2.0, you'd use -set-version 10.

Don't ask why, just vibe with it 😌

🆔 ID stuff

cpdf -copy-id-from source.pdf in.pdf -o out.pdf

Copies the ID from one PDF to another. Stealing the identity, but make it legal 💅

cpdf -remove-id in.pdf -o out.pdf

Removes the ID from a PDF entirely. Poof, gone ✨

🌈 Spot colours

cpdf -list-spot-colors in.pdf

Lists the names of any separation colour spaces hanging out in your PDF. Very niche, very slay.

🧬 Dictionary entry surgery (low level, proceed with care)

cpdf -print-dict-entry <key> in.pdf [-json]

cpdf -remove-dict-entry <key> in.pdf [-dict-entry-search <term>] -o out.pdf

cpdf -replace-dict-entry <key> -replace-dict-entry-value <value> in.pdf [-dict-entry-search <term>] -o out.pdf

These are low level operations that edit PDF objects directly. That's the deep end, bestie — you're poking at the actual guts of the file. For the full details, go read cpdfmanual.pdf. 📖

✂️ Clipping, be gone

cpdf -remove-clipping in.pdf [<range>] -o out.pdf

Removes any clipping paths from a PDF. No more being contained by the system 🦋

🧰 Object-level operations (the real deep end)

cpdf -obj[-json] <object specification> in.pdf

cpdf -replace-obj <object specification>=<object> in.pdf -o out.pdf

cpdf -remove-obj <object number> in.pdf -o out.pdf

cpdf -extract-stream[-decompress] <object specification> in.pdf -o out.dat

cpdf -replace-stream <object specification> -replace-stream-with <filename> in.pdf -o out.pdf

These are low level operations to explore and edit PDF files object-by-object. Like, literally one object at a time. This is surgeon hours 🔬 For details, again: cpdfmanual.pdf. 🫶

🕵️ JavaScript check

cpdf -contains-javascript in.pdf

Prints true if the PDF contains JavaScript, and false if it doesn't. A little vibe check for sneaky scripts 👀

cpdf -remove-javascript in.pdf -o out.pdf

Removes JavaScript from a PDF. Scrubbing the place clean 🧽✨

🌸 ENVIRONMENT 🌸

These are the lil environment variables that change how cpdf behaves. Set them and watch the magic happen 🪄

  • CPDF_SHOW_EXT — shows the command line of external commands as they get called, if it's equal to “true”.
  • CPDF_DEBUG — does the exact same thing as adding -debug to the command line, if it's equal to “true”.
  • CPDF_REPRODUCIBLE_DATES — expands the data “now” to the same, false value every single time, if it's equal to “true”.
  • CAMLPDF_REPRODUCIBLE_IDS — produces the same file ID each time, if it's equal to “true”.

😭 BUGS 😭

Found a bug? Spill the tea here:

We love a report, fr fr 🫶

👑 AUTHORS 👑

Coherent Graphics Ltd. — the masterminds behind all this. Absolute main character energy ✨

And that's a wrap on the whole cpdf(1) page, bestie!! 🎀 You just read every last section and I'm so proud of you. This lil slice came from the February 2026 edition of the manual, and the page is filed under CPDF(1) — so if you ever need to find it again, that's your girl 💖

Go forth and PDF like the icon you are. Slay. Periodt. 💅🦋🌸

📦 where this page comes from