### Visualize Layout Regions with Guides

Source: https://pdfcpu.io/create/create_general

Enable the global 'guides' flag to visualize layout regions defined by 'guides'. A guide is a haircross of horizontal and vertical lines. Use -1 for a coordinate to center it within the content box width or height.

```bash
pdfcpu guides in.pdf out.pdf
```

--------------------------------

### Install pdfcpu CLI using Go

Source: https://pdfcpu.io/getting_started/install_cli

Install the pdfcpu CLI tool using the Go package manager. Ensure Go is installed and configured on your system. Run `pdfcpu version` to confirm installation.

```bash
go install github.com/pdfcpu/pdfcpu/cmd/pdfcpu@latest
pdfcpu version

```

--------------------------------

### Customize Multistamp Start Pages

Source: https://pdfcpu.io/core/stamp

Example of customizing multistamping by specifying the starting page for both the stamp PDF and the input PDF.

```bash
$ pdfcpu stamp add 'stamp.pdf:2:3' '' in.pdf out.pdf --mode pdf

```

--------------------------------

### Example pdfcpu Configuration Output

Source: https://pdfcpu.io/config/config_list

This is an example of the output generated by the 'pdfcpu config list' command, showing the configuration file path and its detailed settings.

```yaml
$pdfcpu config list
config: /Users/horstrutter/Library/Application Support/pdfcpu/config.yml

#############################
#   Default configuration   #
#############################

# Creation date
created: 2026-03-31 00:33

# version (Do not edit!)
version: v0.12.0 dev

# toggle for inFilename extension check (.pdf)
checkFileNameExt: true

reader15: true

decodeAllStreams: false

# validationMode:
# ValidationStrict,
# ValidationRelaxed,
validationMode: ValidationRelaxed

# validate cross reference table right before writing.
postProcessValidate: true

# eol for writing:
# EolLF
# EolCR
# EolCRLF
eol: EolLF

writeObjectStream: true
writeXRefStream: true
encryptUsingAES: true

# encryptKeyLength: max 256
encryptKeyLength: 256

# permissions for encrypted files:
# 0xF0C3 (PermissionsNone)
# 0xF8C7 (PermissionsPrint)
# 0xFFFF (PermissionsAll)
# See more at model.PermissionFlags and PDF spec table 22
permissions: 0xF0C3

# displayUnit:
# points
# inches
# cm
# mm
unit: points

# timestamp format: yyyy-mm-dd hh:mm
# Switch month and year by using: 2006-02-01 15:04
# See more at https://pkg.go.dev/time@go1.22#pkg-constants
timestampFormat: 2006-01-02 15:04

# date format: yyyy-mm-dd
dateFormat: 2006-01-02

# toggle optimization.
optimize: true

# optimize page resources via content stream analysis.
optimizeResourceDicts: true

# optimize duplicate content streams across pages.
optimizeDuplicateContentStreams: false

# merge creates bookmarks.
createBookmarks: true

# viewer is expected to supply appearance streams for form fields.
needAppearances: false

# internet availability.
offline: false

# http timeout in seconds.
timeout: 5

# http timeout in seconds for CRL revocation checking.
timeoutCRL: 10

# http timeout in seconds for OCSP revocation checking.
timeoutOCSP: 10

# preferred certificate revocation checking mechanism:
# crl
# ocsp
preferredCertRevocationChecker: crl

# limit form field content for display purposes when using pdfcpu form list.
# if > 0 affects the columns AltName, Default and Value.
FormFieldListMaxColWidth: 0

```

--------------------------------

### Install pdfcpu CLI using DNF/YUM

Source: https://pdfcpu.io/getting_started/install_cli

Install the pdfcpu CLI tool on Fedora systems using DNF or YUM package managers. Run `pdfcpu version` to confirm installation.

```bash
sudo dnf install golang-github-pdfcpu
pdfcpu version

```

--------------------------------

### Install pdfcpu Go Library

Source: https://pdfcpu.io/getting_started/install_api

Use this command to install the latest version of the pdfcpu Go library.

```bash
go get github.com/pdfcpu/pdfcpu@latest

```

--------------------------------

### Install pdfcpu CLI using Homebrew

Source: https://pdfcpu.io/getting_started/install_cli

Install the pdfcpu CLI tool on macOS using the Homebrew package manager. Run `pdfcpu version` to verify the installation.

```bash
brew install pdfcpu
pdfcpu version

```

--------------------------------

### List Configuration

Source: https://pdfcpu.io/getting_started/usage

Lists the current pdfcpu configuration settings. No setup is required.

```bash
pdfcpu config list [flags]
```

--------------------------------

### Install pdfcpu CLI using MacPorts

Source: https://pdfcpu.io/getting_started/install_cli

Install the pdfcpu CLI tool on macOS using the MacPorts package manager. Run `pdfcpu version` to verify the installation.

```bash
sudo port install pdfcpu
pdfcpu version

```

--------------------------------

### Get File Information

Source: https://pdfcpu.io/getting_started/usage

Prints detailed information about one or more PDF files. No setup is required.

```bash
pdfcpu info inFile... [flags]
```

--------------------------------

### Example: Reset and List Page Mode

Source: https://pdfcpu.io/pagemode/pagemode_reset

This example demonstrates resetting the page mode for 'test.pdf' and then listing the current page mode. After resetting, no page mode is set, and PDF viewers will default to 'UseNone'.

```bash
$ pdfcpu pagemode reset test.pdf
$ pdfcpu pagemode list test.pdf
No page mode set, PDF viewers will default to "UseNone"
```

--------------------------------

### Encrypt PDF and Change Owner Password Example

Source: https://pdfcpu.io/encrypt/change_opw

This example demonstrates how to first encrypt a PDF file with an owner password and then subsequently change that owner password using pdfcpu. Ensure the old owner password is correct when changing it.

```bash
$ pdfcpu encrypt enc.pdf --opw opw
writing enc.pdf ...

```

```bash
$ pdfcpu changeopw enc.pdf opw opwNew
writing enc.pdf ...

```

--------------------------------

### Example Configuration File Version

Source: https://pdfcpu.io/config/config_reset

Shows the version specified within the config.yml file. This is used to compare against the running pdfcpu version to determine if a configuration upgrade is needed.

```yaml
# version (Do not edit!)
version: v0.9.0 dev

```

--------------------------------

### Set All Permissions Example

Source: https://pdfcpu.io/encrypt/perm_set

Sets all permissions for an encrypted PDF. Requires the owner password to be provided.

```bash
$ pdfcpu perm set enc.pdf --opw opw --perm all
adding permissions to enc.pdf ...
writing enc.pdf ...

```

--------------------------------

### Example JSON Output

Source: https://pdfcpu.io/bookmarks/bookmarks_export

This is an example of the JSON structure generated when exporting bookmarks. It includes header information and a list of bookmarks with their properties and nested structure.

```json
{
	"header": {
		"source": "bookmarkTree.pdf",
		"version": "pdfpdfcpu v0.5.0 dev",
		"creation": "2023-08-19 12:53:28 CEST",
		"title": "The Center of Why?",
		"author": "Alan Kay",
		"creator": "Acrobat PDFMaker 5.0 for Word",
		"producer": "pdfcpu v0.4.1 dev",
		"subject": "2004 Kyoto Prize Commemorative Lecture"
	},
	"bookmarks": [
		{
			"title": "Page 1: Level 1",
			"page": 1,
			"color": {
				"R": 0,
				"G": 1,
				"B": 0
			},
			"kids": [
				{
					"title": "Page 2: Level 1.1",
					"page": 2
				},
				{
					"title": "Page 3: Level 1.2",
					"page": 3,
					"kids": [
						{
							"title": "Page 4: Level 1.2.1",
							"page": 4
						}
					]
				}
			]
		},
		{
			"title": "Page 5: Level 2",
			"page": 5,
			"color": {
				"R": 0,
				"G": 0,
				"B": 1
			},
			"kids": [
				{
					"title": "Page 6: Level 2.1",
					"page": 6
				},
				{
					"title": "Page 7: Level 2.2",
					"page": 7
				},
				{
					"title": "Page 8: Level 2.3",
					"page": 8
				}
			]
		}
	]
}
```

--------------------------------

### Zoom out with border and background color

Source: https://pdfcpu.io/core/zoom

This example demonstrates zooming out by a vertical margin, drawing a border around the content, and setting a background color. The unit can be specified, defaulting to points.

```bash
$ pdfcpu zoom 'vmargin: 1, border:true, bgcolor:lightgray' in.pdf out.pdf --unit inch

```

--------------------------------

### List Keywords from a PDF File

Source: https://pdfcpu.io/keywords/keywords_list

Example of how to list all document keywords from 'in.pdf'. The output shows the extracted keywords.

```bash
$pdfcpu keyword list in.pdf
literature
contemporary
```

--------------------------------

### Example: List All Embedded Images

Source: https://pdfcpu.io/images/images_list

This example demonstrates how to list all embedded images in 'test.pdf'. The output includes details such as page number, object ID, image type, dimensions, colorspace, and filter.

```bash
$ pdfcpu images list test.pdf
pages: all
4 images available
Page  Obj# | Id  | Type  SoftMask ImgMask | Width | Height | Colorspace Comp bpc Interp |   Size | Filters
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   1    3 | Im0 | image    *             |  1667 |   2646 |  DeviceRGB    3   8        | 787 KB | DCTDecode
   2   10 | Im0 | image    *             |  1667 |   2646 | DeviceGray    1   8        | 1.6 MB | FlateDecode
   3    8 | Im0 | image    *             |  1667 |   2646 |  DeviceRGB    3   8        | 1.7 MB | FlateDecode
   4    9 | Im0 | image    *             |  1667 |   2646 |  DeviceRGB    3   8    *   | 3.8 MB | FlateDecode

```

--------------------------------

### Encrypt PDF Example

Source: https://pdfcpu.io/encrypt/perm_set

This command encrypts a PDF file, which is a prerequisite for setting permissions.

```bash
$ pdfcpu encrypt enc.pdf --opw opw
writing enc.pdf ...

```

--------------------------------

### Create Booklet from Image Files

Source: https://pdfcpu.io/generate/booklet

Generates a 4-up booklet from a sequence of PNG image files. This example includes guidelines, a margin of 25, and a custom background color, outputting to bookletFromImages.pdf.

```shell
$ pdfcpu booklet 'p:A4, g:on, ma:25, bgcol:#beded9' bookletFromImages.pdf 4 *.png
```

--------------------------------

### Get Help for a Specific Command

Source: https://pdfcpu.io/getting_started/usage

Use this command to get detailed help for any specific pdfcpu command. This is useful for understanding command-specific flags and options.

```bash
pdfcpu [command] --help

```

--------------------------------

### Print Version

Source: https://pdfcpu.io/getting_started/usage

Prints the current pdfcpu version. No setup is required.

```bash
pdfcpu version [flags]
```

--------------------------------

### List Viewer Preferences

Source: https://pdfcpu.io/getting_started/usage

Lists the current viewer preferences for a PDF file. No setup is required.

```bash
pdfcpu viewerpref list inFile [flags]
```

--------------------------------

### List PDF Permissions Example

Source: https://pdfcpu.io/encrypt/perm_set

Lists the current permission bits set for an encrypted PDF. This helps in understanding the effect of permission changes.

```bash
$ pdfcpu perm list enc.pdf
permission bits: 000000000000 (x000)
Bit  3: false (print(rev2), print quality(rev>=3))
Bit  4: false (modify other than controlled by bits 6,9,11)
Bit  5: false (extract(rev2), extract other than controlled by bit 10(rev>=3))
Bit  6: false (add or modify annotations)
Bit  9: false (fill in form fields(rev>=3)
Bit 10: false (extract(rev>=3))
Bit 11: false (modify(rev>=3))
Bit 12: false (print high-level(rev>=3))


```

--------------------------------

### Install TrueType Font with pdfcpu

Source: https://pdfcpu.io/fonts/fonts_install

Use this command to install a single TrueType font file (e.g., .ttf) for use with pdfcpu. The font will be installed in the user's application support directory.

```bash
$ pdfcpu font install SimSun.ttf
installing to /Users/horstrutter/Library/Application Support/pdfcpu/fonts...
SimSun

```

--------------------------------

### Display pdfcpu Version and Config Path

Source: https://pdfcpu.io/getting_started/config_dir

Use the 'pdfcpu version' command to display the current version, commit hash, configuration file path, and Go version. This is useful for verifying installation and understanding the active configuration environment.

```bash
$ pdfcpu version
pdfcpu: v0.12.0 dev
commit: adbc7ca2 (2026-04-03T17:15:58Z)
config: /Users/horstrutter/Library/Application Support/pdfcpu/config.yml
base  : go1.26.1


```

--------------------------------

### Go Text Box Example

Source: https://pdfcpu.io/create/create_general

Creates a simple page using A6 landscape mode with a text box positioned at (50/100) using 24pt Helvetica. Assumes the default coordinate system with origin in the lower-left corner.

```go
pdfcpu.Create(
	"a6 landscape"
```

--------------------------------

### Install TrueType Collection with pdfcpu

Source: https://pdfcpu.io/fonts/fonts_install

Use this command to install fonts from a TrueType collection file (e.g., .ttc). Multiple font faces within the collection will be registered for use with pdfcpu.

```bash
$ pdfcpu font install Songti.ttc
installing to /Users/horstrutter/Library/Application Support/pdfcpu/fonts...
STSongti-SC-Black
STSongti-SC-Bold
STSongti-TC-Bold
STSongti-SC-Light
STSong
STSongti-SC-Regular

```

--------------------------------

### List Page Layout of test2.pdf

Source: https://pdfcpu.io/pagelayout/pagelayout_list

Example of listing the page layout for a PDF file named 'test2.pdf'. This output indicates that the 'TwoPageLeft' page layout is configured.

```bash
$ pdfcpu pagelayout list test2.pdf
TwoPageLeft

```

--------------------------------

### Remove All Bookmarks Example

Source: https://pdfcpu.io/bookmarks/bookmarks_remove

Demonstrates how to remove all bookmarks from a PDF file. After removal, you can list bookmarks to verify they are gone.

```bash
$ pdfcpu bookmarks remove bookmarkSimple.pdf
```

```bash
no bookmarks available
```

--------------------------------

### List Bookmarks

Source: https://pdfcpu.io/getting_started/usage

Lists all bookmarks within a PDF file. No setup is required.

```bash
pdfcpu bookmarks list inFile [flags]
```

--------------------------------

### Reset Configuration

Source: https://pdfcpu.io/getting_started/usage

Resets pdfcpu configuration settings to their default values. No setup is required.

```bash
pdfcpu config reset [flags]
```

--------------------------------

### Demonstrate Text Alignment Options

Source: https://pdfcpu.io/create/create_general

Showcase different text alignment options ('left', 'center', 'right', 'justify') within text boxes. This example uses named text boxes and fonts for consistency.

```json
{
  "version": 1,
  "texts": [
    {
      "name": "sample1",
      "value": "This is a centered text.",
      "font": "myFont",
      "size": 12,
      "align": "center",
      "color": [0.1, 0.2, 0.3],
      "pos": [100, 100]
    },
    {
      "name": "sample2",
      "value": "This is a left aligned text.",
      "font": "myFont",
      "size": 12,
      "align": "left",
      "color": [0.1, 0.2, 0.3],
      "pos": [100, 120]
    },
    {
      "name": "sample2",
      "value": "This is a right aligned text.",
      "font": "myFont",
      "size": 12,
      "align": "right",
      "color": [0.1, 0.2, 0.3],
      "pos": [100, 140]
    },
    {
      "name": "sample2",
      "value": "This is a justified text.",
      "font": "myFont",
      "size": 12,
      "align": "justify",
      "color": [0.1, 0.2, 0.3],
      "pos": [100, 160]
    }
  ],
  "fonts": [
    {
      "name": "myFont",
      "file": "./Helvetica.ttf"
    }
  ]
}
```

--------------------------------

### Add Pictures to PDF Portfolio

Source: https://pdfcpu.io/portfolio/portfolio_add

Example of adding multiple JPG images to an existing PDF portfolio. The command processes the specified files and updates the portfolio.

```bash
$ pdfcpu portfolio add portfolio.pdf *.jpg
writing portfolio.pdf ...

```

--------------------------------

### PDF Optimization Stats Output

Source: https://pdfcpu.io/core/optimize

This example shows the header and a sample data line from a CSV stats file generated by the optimize command. It includes metrics on file size, resource usage, and PDF object details.

```csv
$ cat stats.csv
name;version;author;creator;producer;src_size (bin|text);src_bin:imgs|fonts|other;dest_size (bin|text);dest_bin:imgs|fonts|other;linearized;hybrid;xrefstr;objstr;pages;objs;missing;garbage;R_Version;R_Extensions;R_PageLabels;R_Names;R_Dests;R_ViewerPrefs;R_PageLayout;R_PageMode;R_Outlines;R_Threads;R_OpenAction;R_AA;R_URI;R_AcroForm;R_Metadata;R_StructTreeRoot;R_MarkInfo;R_Lang;R_SpiderInfo;R_OutputIntents;R_PieceInfo;R_OCProperties;R_Perms;R_Legal;R_Requirements;R_Collection;R_NeedsRendering;P_LastModified;P_Resources;P_MediaBox;P_CropBox;P_BleedBox;P_TrimBox;P_ArtBox;P_BoxColorInfo;P_Contents;P_Rotate;P_Group;P_Thumb;P_B;P_Dur;P_Trans;P_Annots;P_AA;P_Metadata;P_PieceInfo;P_StructParents;P_ID;P_PZ;P_SeparationInfo;P_Tabs;P_TemplateInstantiated;P_PresSteps;P_UserUnit;P_VP;
test.pdf;1.2;;;;6 KB (67.4% | 32.6%); 0.0% |  0.0% | 100.0%;5 KB (86.6% | 13.4%); 0.0% |  0.0% | 100.0%;false;false;false;false;2;15;;;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;true;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false;false
```

--------------------------------

### Manage PDF Fonts

Source: https://pdfcpu.io/getting_started/usage

Commands for listing available fonts, installing new font files, and generating font cheatsheets.

```bash
pdfcpu fonts list [flags]

```

```bash
pdfcpu fonts install fontFiles... [flags]

```

```bash
pdfcpu fonts cheatsheet fontFiles... [flags]

```

--------------------------------

### List Page Layout of test1.pdf

Source: https://pdfcpu.io/pagelayout/pagelayout_list

Example of listing the page layout for a PDF file named 'test1.pdf'. If no page layout is explicitly set, PDF viewers default to 'SinglePage'.

```bash
$ pdfcpu pagelayout list test1.pdf
No page layout set, PDF viewers will default to "SinglePage"

```

--------------------------------

### Create 4-up Booklet with Customizations

Source: https://pdfcpu.io/generate/booklet

Creates a 4-up booklet with A4 paper size, borders disabled, guidelines enabled, a margin of 10, and a custom background color. This command aids in understanding assembly steps by visualizing cutting and folding guides.

```shell
$ pdfcpu booklet 'p:A4, bo:off, g:on, ma:10, bgcol:#beded9' zine.pdf 4 pageSequence.pdf
```

--------------------------------

### Split PDF by Bookmarks

Source: https://pdfcpu.io/core/split

Example of splitting a PDF file based on its existing bookmarks. Each output file will represent a section defined by a bookmark. The '-m bookmark' flag is used for this mode.

```bash
$ pdfcpu split test.pdf out -m bookmark

```

--------------------------------

### pdfcpu Create Command Help

Source: https://pdfcpu.io/create/create

Display detailed help information for the pdfcpu create command to understand all available options and flags.

```bash
$ pdfcpu create --help

```

--------------------------------

### Add Multiple Boxes with Relative Units

Source: https://pdfcpu.io/boxes/boxes_add

Example of adding multiple boxes (Crop, Bleed, Art, Trim) using relative units (inches) and relative margins. It also shows assigning boxes to each other.

```bash
$ pdfcpu box add 'c:1, b:15%, a:b, t:b' in.pdf out.pdf -u inches
adding cropBox, trimBox, bleedBox, artBox for test.pdf
writing out.pdf...
pages: all


```

--------------------------------

### Split PDF into Files with 2-Page Spans

Source: https://pdfcpu.io/core/split

Example demonstrating how to split a PDF file into output files, with each output file containing 2 pages from the original document. The output files are saved in the 'out' directory.

```bash
$ pdfcpu split test.pdf out 2

```

--------------------------------

### Validate PDF File using pdfcpu API

Source: https://pdfcpu.io/getting_started/install_api

This example demonstrates how to validate an input PDF file using the api.ValidateFile function. Ensure the input.pdf file exists in the same directory or provide the correct path. Errors during validation will be logged.

```go
package main

import (
    "log"

    "github.com/pdfcpu/pdfcpu/pkg/api"
)

func main() {
    if err := api.ValidateFile("input.pdf", nil); err != nil {
        log.Fatal(err)
    }
}

```

--------------------------------

### Import Image to Fixed Size PDF with Full Scaling

Source: https://pdfcpu.io/generate/import

Creates a 500x500 PDF, anchoring the image to the top-left corner with a scaling of 1.

```bash
$ pdfcpu import 'dim:500 500, pos:tl, sc:1' photo.pdf photo.jpg
```

--------------------------------

### pdfcpu Create Sample Output Directory

Source: https://pdfcpu.io/create/create

Location of sample output files generated by the pdfcpu create command.

```bash
pdfcpu/pkg/samples/create/*

```

--------------------------------

### List PDF Certificates

Source: https://pdfcpu.io/core/certs

Use this command to list all available certificates.

```bash
pdfcpu certificates list
```

--------------------------------

### List All Viewer Preferences in JSON

Source: https://pdfcpu.io/viewerpref/viewerpref_list

Use this command to display all viewer preferences, including default values, in JSON format. Ensure the PDF file exists.

```bash
pdfcpu viewerpref list -all -json test.pdf
```

--------------------------------

### Select First Three Pages, Page 5, and Page 7 to End

Source: https://pdfcpu.io/getting_started/page_selection

Use this syntax to select a combination of initial pages, a specific page, and a range from a certain page to the end of the document.

```bash
--pages -3,5,7-
```

--------------------------------

### Reset Viewer Preferences

Source: https://pdfcpu.io/getting_started/usage

Resets viewer preferences for a PDF file to default values. No setup is required.

```bash
pdfcpu viewerpref reset inFile [flags]
```

--------------------------------

### pdfcpu Create Sample JSON Input Directory

Source: https://pdfcpu.io/create/create

Location of sample JSON files used for creating PDFs with pdfcpu.

```bash
pdfcpu/pkg/testdata/json/*

```

--------------------------------

### Default grid description configuration

Source: https://pdfcpu.io/generate/grid

Shows the default configuration string for grid layout. Specify only parameters that differ from the default.

```bash
'form:A4, d:595 842, o:rd, bo:on, ma:3, enforce:on'
```

--------------------------------

### Select Pages

Source: https://pdfcpu.io/getting_started/usage

Prints the definition of the -pages flag, which is used for selecting specific pages in operations. No setup is required.

```bash
pdfcpu selectedpages [flags]
```

--------------------------------

### pdfcpu Create Command Usage

Source: https://pdfcpu.io/create/create

Basic syntax for the pdfcpu create command. Specify the JSON input file, an optional existing PDF file, the output PDF file, and any relevant flags.

```bash
pdfcpu create inFileJSON [ inFile ] outFile [flags]

```

--------------------------------

### Specify Color via RGB Hexadecimal Values

Source: https://pdfcpu.io/getting_started/color

Use hexadecimal format #RRGGBB to define colors. Example: Red is #FF0000.

```text
#RRGGBB

eg. Red = #FF0000, Gray = #808080
```

--------------------------------

### Import Image with Sepia Effect

Source: https://pdfcpu.io/generate/import

Creates a PDF from an image with a sepia effect applied.

```bash
$ pdfcpu import 'sepia:true' sepia.pdf test.jpg
```

--------------------------------

### Remove Crop Box for All Pages

Source: https://pdfcpu.io/boxes/boxes_remove

Example showing how to remove only the crop box for all pages of an input PDF file, specifying the output file.

```bash
$ pdfcpu boxes remove 'crop' in.pdf out.pdf
removing cropBox for in.pdf
writing out.pdf...
pages: all

```

--------------------------------

### Extract all portfolio entries

Source: https://pdfcpu.io/portfolio/portfolio_extract

This command extracts all entries from a PDF portfolio into the specified output directory. It's a convenient way to get all contents of a portfolio.

```bash
$ pdfcpu portfolio extract portfolio.pdf out
```

--------------------------------

### Build and run pdfcpu using Docker

Source: https://pdfcpu.io/getting_started/install_cli

Build a Docker image for pdfcpu and run a container to validate a PDF file. Mount the current directory to the container's app directory for file access.

```bash
docker build -t pdfcpu .
docker run -it -v "$(pwd)":/app pdfcpu validate a.pdf

```

--------------------------------

### Create Cheat Sheets for All User Fonts

Source: https://pdfcpu.io/fonts/fonts_cheat

Generates cheat sheets for all user fonts installed on the system. This command iterates through available fonts and creates a cheat sheet for each.

```bash
$ pdfcpu font cheat
creating cheatsheets for: Roboto-Regular
creating cheatsheets for: STSong
creating cheatsheets for: STSongti-SC-Black
creating cheatsheets for: STSongti-SC-Bold
creating cheatsheets for: STSongti-SC-Light
creating cheatsheets for: STSongti-SC-Regular
creating cheatsheets for: STSongti-TC-Bold
creating cheatsheets for: STSongti-TC-Light
creating cheatsheets for: STSongti-TC-Regular
creating cheatsheets for: SimSun
creating cheatsheets for: Unifont-JPMedium
creating cheatsheets for: UnifontMedium
creating cheatsheets for: UnifontUpperMedium


```

--------------------------------

### Import Images to Album with Specific Paper Size and Offsets

Source: https://pdfcpu.io/generate/import

Generates a PDF album on Letter paper, anchoring images to the bottom-left with specified offsets and scaling.

```bash
$ pdfcpu import 'f:Letter, pos:bl, off:10 20, scale:0.3' album.pdf *.jpg *.png
```

--------------------------------

### Apply Horizontal Page Cut

Source: https://pdfcpu.io/generate/cut

Example of applying a horizontal page cut at 0.25 height. This results in a PDF containing 3 PDF pages for each processed page.

```bash
$ pdfcpu cut 'hor:.25' test.pdf .
cutting test.pdf into ./ ...
writing test_page_1.pdf
```

--------------------------------

### Import Image to Fixed Size PDF with Relative Scaling

Source: https://pdfcpu.io/generate/import

Creates a 500x500 PDF, anchoring the image to the top-left corner with a relative scaling of 0.3.

```bash
$ pdfcpu import 'dim:500 500, pos:tl, sc:0.3 rel' photo.pdf photo.jpg
```

--------------------------------

### Specify Color via RGB Float Values

Source: https://pdfcpu.io/getting_started/color

Use RGB float values between 0.0 and 1.0 to define colors. Example: Red is 1.0, 0.0, 0.0.

```text
r,g,b with 0.0 <= r,g,b <= 1.0

eg. Red = 1.0, 0.0, 0.0, Gray = .5, .5, .5
```

--------------------------------

### List All Viewer Preferences

Source: https://pdfcpu.io/viewerpref/viewerpref_list

Use this command to display all viewer preferences, including default values, for a PDF file. Ensure the PDF file exists.

```bash
pdfcpu viewerpref list test.pdf --all
```

--------------------------------

### Import Image to PDF with Default Settings

Source: https://pdfcpu.io/generate/import

Creates a single-page PDF from an image, matching page dimensions to image dimensions.

```bash
$ pdfcpu import photo.pdf photo.png
```

--------------------------------

### Add Crop Box to PDF

Source: https://pdfcpu.io/boxes/boxes_add

Example of adding a Crop Box to a PDF file. This command sets a specific rectangular region as the Crop Box, relative to the Media Box.

```bash
$ pdfcpu box add 'crop:[0 0 200 200]' in.pdf cropped.pdf
adding cropBox for in.pdf
writing cropped.pdf...
pages: all


```

--------------------------------

### Create 2-up Booklet with Customizations

Source: https://pdfcpu.io/generate/booklet

Creates a 2-up booklet with a specified form size, border disabled, guidelines enabled, a margin of 10, and a custom background color. The command is identical to the one using default form size (A4).

```shell
$ pdfcpu booklet 'formsize:A4, border:off, guide:on, margin:10, bgcol:#beded9' booklet.pdf 2 pageSequence.pdf
```

```shell
$ pdfcpu booklet 'g:on, ma:10, bgcol:#beded9' booklet.pdf 2 pageSequence.pdf
```

--------------------------------

### Select Page Range and Exclude Specific Page

Source: https://pdfcpu.io/getting_started/page_selection

This example demonstrates selecting a range of pages while excluding a specific page within that range. Note the use of single quotes for the exclusion.

```bash
--pages '4-7,!6'
```

--------------------------------

### Import Image with Grayscale Effect

Source: https://pdfcpu.io/generate/import

Creates a PDF from an image with a grayscale effect applied.

```bash
$ pdfcpu import 'gray:true' gray.pdf test.jpg
```

--------------------------------

### Import pdfcpu API Package

Source: https://pdfcpu.io/getting_started/install_api

Import the pdfcpu API package to use its functionalities in your Go project.

```go
import "github.com/pdfcpu/pdfcpu/pkg/api"

```

--------------------------------

### Add PDF Page Stamp

Source: https://pdfcpu.io/core/stamp

Example of using a specific page from another PDF file as a stamp. The page number is specified using a colon separator after the stamp file name.

```bash
$ pdfcpu stamp add --mode pdf -- 'stamp.pdf:1' '' in.pdf out.pdf

```

--------------------------------

### Add Text Stamp with Formatting

Source: https://pdfcpu.io/core/stamp

Example of adding a text stamp to a PDF. It demonstrates using format strings for page numbers and configuring stamp properties like scale, position, and rotation.

```bash
$ pdfcpu stamp add --mode text -- 'Page %p of %P' 'scale:1.0 abs, pos:bc, rot:0' in.pdf out.pdf

```

--------------------------------

### Create Custom Page Collection

Source: https://pdfcpu.io/core/collect

Example of creating a custom page collection. This command takes pages 1, 1, 1, and then pages 2 through the second-to-last page from 'in.pdf' and saves them to 'out.pdf'.

```bash
$ pdfcpu collect in.pdf out.pdf --pages 1,1,1,2-l-1 
writing sequ.pdf ...

```

--------------------------------

### Create a 2x5 image grid with custom dimensions

Source: https://pdfcpu.io/generate/grid

Arranges image files ('*.jpg') into a 2x5 grid on a page with cell dimensions of 500x500 units, a margin of 20, and borders disabled. Saves the result to 'out.pdf'.

```bash
$ pdfcpu grid 'd:500 500, ma:20, bo:off' out.pdf 2 5 *.jpg
```

--------------------------------

### List User Fonts Directory Structure

Source: https://pdfcpu.io/getting_started/config_dir

The 'tree' command can also display the structure of the 'fonts' directory, showing the internal representations of installed user fonts. These .gob files are stored in the config directory.

```bash
$ tree
..
├── certs
├── config.yml
└── fonts
    ├── Roboto-Regular.gob
    ├── Unifont-JPMedium.gob
    ├── UnifontMedium.gob
    └── UnifontUpperMedium.gob


```

--------------------------------

### Basic N-up Command Usage

Source: https://pdfcpu.io/generate/nup

Applies a 4-up layout to 'in.pdf', fitting 4 original pages onto each new page in a 2x2 grid, saving to 'out.pdf'.

```bash
$ pdfcpu nup out.pdf 4 in.pdf
```

--------------------------------

### Manage PDF Portfolios

Source: https://pdfcpu.io/getting_started/usage

Commands for managing PDF portfolios, including listing, adding, removing, and extracting files within a portfolio.

```bash
pdfcpu portfolio list inFile [flags]

```

```bash
pdfcpu portfolio add inFile file... [flags]

```

```bash
pdfcpu portfolio remove inFile [ file... ] [flags]

```

```bash
pdfcpu portfolio extract inFile outDir [ file... ] [flags]

```

--------------------------------

### Split PDF Before Specific Pages

Source: https://pdfcpu.io/core/split

Example of splitting a PDF file before specific page numbers. The '-m page' flag indicates page-based splitting, followed by the list of page numbers before which the split should occur.

```bash
$ pdfcpu split -m page test.pdf out 2 4 10

```

--------------------------------

### List Viewer Preferences in JSON

Source: https://pdfcpu.io/viewerpref/viewerpref_list

Use this command to display non-default viewer preferences in JSON format. Ensure the PDF file exists.

```bash
pdfcpu viewerpref list -json test.pdf
```

--------------------------------

### Import Certificates with pdfcpu

Source: https://pdfcpu.io/core/certs

Use this command to import additional certificates into pdfcpu's managed certificate store. This is useful for users in regions not covered by the preloaded certificates.

```bash
$ pdfcpu certificates import hr.p7c
hr.p7c: 156 certificates
imported 156 certificates

```

--------------------------------

### Remove Specific Page Boxes

Source: https://pdfcpu.io/boxes/boxes_remove

Example demonstrating how to remove crop, bleed, art, and trim boxes for a specific page (page 2) of an input PDF file, saving the result to an output file.

```bash
$ pdfcpu boxes remove 'c,b,a,t' in.pdf out.pdf --pages 2
removing cropBox, trimBox, bleedBox, artBox for in.pdf
writing out.pdf...

```

--------------------------------

### List specific page boundaries with custom units

Source: https://pdfcpu.io/boxes/boxes_list

This command lists only the mediaBox and cropBox for a specific page (page 1) and displays the dimensions in centimeters. Ensure the box types are comma-separated and the page is specified using the --pages flag.

```bash
$ pdfcpu box list 'm,c' test.pdf --pages 1 --unit cm
listing mediaBox, cropBox for test.pdf
pages: 1
Page 1: rot=+0 orientation:portrait
  MediaBox (cm) (0.00, 0.00, 21.00, 29.70) w=21.00 h=29.70 ar=0.71 (inherited)
   CropBox (cm) (0.00, 0.00, 21.00, 29.70) w=21.00 h=29.70 ar=0.71 (default)

```

--------------------------------

### Apply Horizontal and Vertical Page Cuts

Source: https://pdfcpu.io/generate/cut

Example of applying both a horizontal page cut at 0.25 height and a vertical page cut at 0.75 width. This results in a PDF containing 5 pages for each processed page.

```bash
$ pdfcpu cut 'hor:.25, vert:.75' test.pdf .
cutting test.pdf into ./ ...
writing test_page_1.pdf
```

--------------------------------

### Import Multiple Images to Create Photo Album

Source: https://pdfcpu.io/generate/import

Generates a PDF photo album from all image files in a specified directory.

```bash
$ pdfcpu import album.pdf pics/*
```

--------------------------------

### Split PDF into Single Page Files

Source: https://pdfcpu.io/core/split

Example of splitting a PDF file into individual PDF files, where each output file contains a single page from the original document. The output files are saved in the 'out' directory.

```bash
$ pdfcpu split test.pdf out

```

--------------------------------

### Set Viewer Preferences via JSON String

Source: https://pdfcpu.io/viewerpref/viewerpref_set

Use this command to set general viewer preferences like hiding the menu bar or centering the window. The JSON string is case-agnostic.

```bash
$ pdfcpu viewerpref set test.pdf "{\"HideMenuBar\": true, \"CenterWindow\": true}"
```

--------------------------------

### N-up for Image Files with Landscape Orientation

Source: https://pdfcpu.io/generate/nup

Renders multiple image files (*.jpg, *.png, *.tif) into 'out.pdf' using a 4-up layout on A4 landscape paper (A4L). Grid borders and default margins are applied.

```bash
$ pdfcpu nup 'form:A4L' out.pdf 4 *.jpg *.png *.tif
```

--------------------------------

### Crop PDF with Relative Dimensions and Offset

Source: https://pdfcpu.io/core/crop

Crops a PDF using relative dimensions and offsets, expressed in centimeters. This example defines a crop box based on a percentage of the media box dimensions with a 1cm offset from the bottom-left.

```bash
$ pdfcpu crop "pos:bl, off:1 1, dim:25% 25%" in.pdf cropped.pdf -u cm

```

--------------------------------

### Config API

Source: https://pdfcpu.io/getting_started/usage

Manage your configuration.

```APIDOC
## Config

Manage your configuration:

### List Configuration

**Method:** GET
**Endpoint:** `/config/list`

### Reset Configuration

**Method:** DELETE
**Endpoint:** `/config/reset`
```

--------------------------------

### pdfcpu Portfolio Add Command Usage

Source: https://pdfcpu.io/portfolio/portfolio_add

This is the general usage syntax for the pdfcpu portfolio add command. Specify the input PDF file and the files to be attached.

```bash
pdfcpu portfolio add inFile file [ , desc ]... [flags]
```

--------------------------------

### Optimize PDF File in Go

Source: https://pdfcpu.io/about/about

Use this function to optimize a PDF file by providing input and output file paths along with a configuration. Ensure the pdf package is imported.

```go
func OptimizeFile(inFile, outFile string, conf *pdf.Configuration) error
```

--------------------------------

### List pdfcpu Managed Certificates

Source: https://pdfcpu.io/core/certs

Use this command to view the certificates that are preloaded and managed by pdfcpu. It shows the certificate directory and details of each certificate.

```bash
$ pdfcpu certificates list
certDir: /Users/horstrutter/Library/Application Support/pdfcpu/certs

/eu/ades-lotl.p7c:
001:
    Subject:
             org       :
             name      : Patrick Kremer (Signature)
             country   : BE
     Issuer:
             org       : Certipost N.V./S.A.
             name      : Citizen CA
             locality  : Brussels
             country   : BE
       from: 2018-06-01
       thru: 2028-05-30
         CA: false

002:
    Subject:
             org       : EUROPEAN COMMISSION
             unit      : Certificate Profile - Qualified Certificate - Member,Entitlement - EC STATUTORY STAFF,RemoteQSCDManagement
             name      : APOSTOLOS APLADAS
             country   : GR
     Issuer:
             org       : DigitalSign Certificadora Digital
             name      : DIGITALSIGN QUALIFIED CA G1
             country   : PT
       from: 2024-04-26
       thru: 2027-04-26
         CA: false

...

/eu/uk.p7c:
001:
    Subject:
             org       : British Telecommunications plc
             unit      : BT Managed Secure Messaging
             name      : BT Managed Secure Messaging Issuing CA FL-CA-3006
     Issuer:
             org       : British Telecommunications plc
             name      : BT Infrastructure for Secure Communication ROOT CA
             country   : GB
       from: 2009-09-22
       thru: 2019-09-22
         CA: true

002:
    Subject:
             org       : Exostar UK Limited
             name      : Exostar Digital Certificate Service Signing CA 1
             country   : GB
     Issuer:
             org       : Exostar LLC
             unit      : Certification Authorities
             name      : Exostar Federated Identity Service Root CA 2
             country   : US
       from: 2016-05-26
       thru: 2026-05-26
         CA: true

003:
    Subject:
             org       : NHS
             unit      : CA
             name      : NHS Root Authority
     Issuer:
             org       : NHS
             unit      : CA
             name      : NHS Root Authority
       from: 2004-06-04
       thru: 2024-06-04
         CA: true

004:
    Subject:
             org       : Police
             name      : Police Service PKI Root Certificate Authority
             country   : GB
     Issuer:
             org       : Police
             name      : Police Service PKI Root Certificate Authority
             country   : GB
       from: 2009-06-10
       thru: 2029-06-10
         CA: true

005:
    Subject:
             org       : Police
             unit      : IAM CS
             name      : Authentication Issuing Authority
             country   : GB
     Issuer:
             org       : Police
             name      : Police Service PKI Root Certificate Authority
             country   : GB
       from: 2010-09-30
       thru: 2020-09-30
         CA: true

006:
    Subject:
             org       : Police
             unit      : Met
             name      : Met Police Class 3 Primary CA
             country   : GB
     Issuer:
             org       : Police
             unit      : Met
             name      : Met Police Root CA
             country   : GB
       from: 2014-11-06
       thru: 2024-11-06
         CA: true

007:
    Subject:
             org       : Police
             unit      : Met
             name      : Met Police Class 3 Secondary CA
             country   : GB
     Issuer:
             org       : Police
             unit      : Met
             name      : Met Police Root CA
             country   : GB
       from: 2014-11-06
       thru: 2024-11-06
         CA: true

008:
    Subject:
             org       : Registers of Scotland
             unit      : ARTL Issuing Authority
             country   : GB
     Issuer:
             org       : Registers of Scotland
             unit      : Registers of Scotland Root CA
             country   : GB
       from: 2006-10-05
       thru: 2016-10-05
         CA: true

009:
    Subject:
             org       : The Royal Bank of Scotland plc
             unit      : The Royal Bank of Scotland plc TrustAssured Infrastructure
             name      : The Royal Bank of Scotland Plc TrustAssured CA
     Issuer:
             org       : IdenTrust Inc.
             unit      : IdenTrust Root Certificate Authority
             name      : IdenTrust Root Certificate Authority
       from: 2013-10-09
       thru: 2020-10-09
         CA: true

total installed certs: 4364
```

--------------------------------

### View pdfcpu Version

Source: https://pdfcpu.io/config/config_reset

Displays the current pdfcpu version, commit hash, configuration file path, and Go version. This is useful for checking compatibility with the configuration file.

```bash
$ pdfcpu version
pdfcpu: v0.9.1 dev
commit: 22ebeff8 (2024-10-18T19:51:48Z)
config: /Users/horstrutter/Library/Application Support/pdfcpu/config.yml
base  : go1.23.0

```