render

press render is the core command. It builds your application (if configured), routes the static artifacts into a headless browser, paginates the page, and exports the result as a PDF.

Usage

press render [entry] [options]

Entry selection

The entry argument selects which [pdf.<name>] section from press.toml to render.

# Render a specific entry
press render report

# If press.toml has only one entry, the name can be omitted
press render

If press.toml defines multiple entries and no entry name is given, the CLI prints all available entries and exits with an error.

Options

Option	Type	Default	Description
--config <path>	string	./press.toml	Path to the config file (resolved from the current directory)
--out <pdf>	string	from config	Override the output PDF file path. .pdf is appended if missing
--timeout <ms>	integer	from config or 30s	Override the per-page render timeout in milliseconds
--timing-detail	boolean	false	Print a detailed timing breakdown of each pipeline step
--remote	boolean	false	Render through Press.js Cloud instead of local Playwright
--save-version	boolean	false	With --remote, keep the cloud deploy/version instead of using a temporary deploy
--remote-output <mode>	string	transient	With --remote, choose transient or managed cloud output retention
--help	—	—	Print the render command usage

Remote renders also accept cloud connection and target flags:

Option	Description
--token <key>	API key for Press.js Cloud authentication
--api-base <url>	Override the Press.js Cloud API base URL
--deploy-id <id>	Target an existing deploy by ID
--slug <slug>	Target or create a deploy by slug
--name <name>	Name used when a deploy is created
--business-key <key>	Business key forwarded to the cloud render job

Pipeline

When you run press render, the following steps execute in order:

1. Load config

The CLI reads press.toml from the current directory (or the path specified by --config). It selects the named entry (or auto-selects if there’s only one).

2. Build (optional)

If the selected entry has a build command, the CLI runs it in the entry’s workspace directory. Output is forwarded to the terminal. If the build fails (non-zero exit code), the render stops.

3. Route artifacts

For local rendering, the CLI intercepts https://press.internal/... requests in Playwright and fulfills them from the entry’s artifact directory. Extensionless routes use index.html as the SPA fallback.

4. Route runtime data

For local rendering, the CLI also intercepts https://p.press.internal/... requests. This provides:

• GET /__payload from payload_path
• GET /environment.json from [runtime.env] and [runtime.secrets]
• pressCloud.env.*, pressCloud.secrets.*, and pressCloud.revokeDataAccess(scope)

Runtime secrets are resolved from .dev.vars and the process environment before the browser starts. See press.toml runtime configuration.

5. Launch browser

Playwright acquires a Chromium browser using the settings from press.toml (see Playwright options). It creates a page with the Press.js user agent and the correct viewport dimensions.

6. Navigate and wait

The browser navigates to the app’s route and waits for the ready signal (window.__pressjsReadyState). If the ready signal doesn’t arrive within the timeout, the render fails.

7. Paginate

The Press.js browser runtime measures the DOM, plans page fragmentation, and resolves overflow. This is the same pipeline that runs in the development preview.

8. Export PDF

Chromium renders the paginated document to PDF at output path.

9. Summary

The CLI prints a render summary:

Entry:      report
Route:      /
Pages:      12
Fragments:  4, 4, 3, 1, ...
Layout:     3 passes
Time:       1842ms
Output:     ./artifacts/my-report.pdf

If there are overflow pages (content that couldn’t fit), they are listed as warnings.

Timing detail

The --timing-detail flag prints a tree of each pipeline step with durations:

press render report --timing-detail

This is useful for identifying performance bottlenecks in your document.

Remote rendering

Use --remote to run the render through Press.js Cloud while keeping the same press.toml entry selection and build step:

press render report --remote

The press CLI still reads press.toml, runs the configured build, validates the artifact directory, and resolves --out/--timeout. It then delegates the cloud work to the installed press-cloud-cli by composing its existing deploy and deploy-management commands.

Local [runtime.env], [runtime.secrets], and .dev.vars values are not forwarded with --remote. Press.js Cloud uses the environment variables and secrets configured on the target deploy. payload_path is forwarded as the render job payload.

By default, remote render creates a temporary deploy, passes the built artifacts to the cloud CLI, writes the PDF to the configured output path (or --out), and deletes the temporary deploy after the cloud command succeeds.

Preserve the deploy/version history with --save-version:

press render report --remote --save-version --slug team-report

Choose cloud output retention with --remote-output:

press render report --remote --remote-output managed

transient is the default and is best for one-off renders. managed persists the rendered PDF as a cloud asset according to Press.js Cloud retention rules.

Remote rendering requires the cloud CLI:

press install cloud

Authentication uses the same cloud settings as press deploy: pass --token, set PRESS_CLOUD_TOKEN, or use an existing interactive login.

Build step details

The build command is configured in press.toml:

[pdf.report]
build = "npm run build"

The CLI:

• Runs the command with shell: true, so pipes and chaining work ("npm run build && cp assets ./dist")
• Sets the working directory to the entry’s workspaceDir
• Forwards stdout and stderr line by line
• Errors on non-zero exit or process signal

To skip the build step at render time, either remove the build field from press.toml or use a separate config file.

Exit codes

Code	Condition
0	Render succeeded
1	Configuration error (missing file, invalid entry, bad arguments)
2	Build step failed
3	Playwright timed out or browser error
4	Pagination engine error