CLI

$ pagr upload report.html
  Uploading…
✓ Published: https://uc.pagr.link/rK9xB2q

1. 1

   Install

   Install the CLI globally via your package manager.

   npm install -g @getpagr/cli

   Copy
2. 2

   Authenticate

   Run pagr login to authenticate via your browser. For CI pipelines, export PAGR_API_KEY instead.

   pagr login

   Copy
3. 3

   Publish

   Run pagr upload with any .html file. The command prints the public URL, copies it to clipboard, and opens it in your browser.

   pagr upload ./report.html
   # → https://uc.pagr.link/rK9xB2q

   Copy

Install

Install the CLI globally when you want pagr available from any terminal.

npm install -g @getpagr/cli

The CLI requires Node.js 20 or newer.

Run pagr without arguments

Running pagr with no arguments is interactive in a TTY:

• under npx @getpagr/cli@latest, it starts the setup wizard
• when signed in, it shows a small menu for init, upload, list, account info, or logout
• when signed out, it asks whether to sign in
• in non-interactive shells and CI, it falls through to command help

Authenticate

Run the login command and choose the browser flow. Pagr opens the app, authenticates with Clerk if needed, creates a CLI API key, and returns it to your terminal through a local callback server on 127.0.0.1. The login session times out after 5 minutes.

pagr login

For headless environments, SSH sessions, or locked-down browsers, use manual paste mode:

pagr login --manual

You can also pass a key directly without prompting:

pagr login --key pagr_...

The CLI stores local configuration in ~/.pagr/config.json. API keys must start with pagr_.

Alternative authentication

You can set the key directly:

pagr config set-key pagr_...

For CI and shared scripts, prefer an environment variable:

export PAGR_API_KEY="pagr_..."

Auth lookup order is PAGR_API_KEY, then ~/.pagr/config.json.

Anonymous uploads

pagr upload file.html works without an API key when you do not pass authenticated-only options. Anonymous uploads:

• expire after 24 hours
• are limited to 1 MB
• are rate-limited to 10 uploads per hour per source IP
• return a claim URL so the page can be saved into an account before expiry

Everything else, including list, delete, update, custom slugs, passwords, and hiding the hosted banner, requires authentication.

Upload a new file

Publish any local .html file.

pagr upload report.html

The command prints the public URL, copies it to the clipboard when possible, and opens it in the browser. Use --no-copy or --no-open to disable either behavior.

Set title and slug

Use --title for dashboard labels and page metadata. Use --slug when you need a stable, readable URL.

pagr upload report.html --slug weekly-report --title "Weekly report"

Custom slugs require a Pro or Team plan. If the account cannot use a custom slug, the API returns a plan error.

Set expiry

Use --ttl or -e to control how long an authenticated page lives. Omitting it uses the account tier default: Free pages expire after 7 days; Pro and Team pages are permanent.

pagr upload report.html --ttl never     # remains until deleted
pagr upload report.html --ttl 24h       # expires in 24 hours
pagr upload report.html --ttl 7d        # expires in 7 days
pagr upload report.html --ttl 30d       # expires in 30 days
pagr upload report.html --ttl 1-visit   # deleted after first view (Pro/Team)

Valid values: never, 24h, 7d, 30d, 1-visit. Free accounts can use 24h and 7d; permanent, 30-day, and read-once pages require Pro or Team.

Password-protect a page

Use --password or -p to require a passphrase before visitors can view the page. Password protection requires Pro or Team.

pagr upload report.html --password "secret"

The password can be changed later from the dashboard or by re-uploading with a new --password.

Hide the hosted banner

By default, Free pages show a small “Hosted on Pagr” banner. Pro and Team users can hide it per file with --hide-banner.

pagr upload report.html --hide-banner

Update an existing file

Update by slug when you know the current URL slug.

pagr upload report.html --update --slug weekly-report

The CLI checks that the authenticated account owns the slug before replacing the HTML. Updates replace the current HTML in place. Pagr does not keep older copies for restore.

Auto-update with metadata

For repeat publishing, let Pagr inject metadata into the source file:

pagr upload report.html --inject

The CLI writes pagr-id and pagr-slug meta tags into the file after upload. Future pagr upload report.html runs detect those tags and update the existing page instead of creating a new one. If an authenticated new upload has no existing pagr-slug, the CLI injects metadata automatically.

Update priority:

1. pagr-id updates by stable document ID.
2. pagr-slug updates by slug.
3. --update --slug forces update by slug.
4. Otherwise Pagr creates a new file.

List files

pagr ls
pagr ls --limit 20
pagr list --limit 20

The default limit is 50. Output includes slug, views, plan, title, and URL.

Remove files

pagr rm weekly-report
pagr rm weekly-report --yes
pagr delete weekly-report -y

Without --yes, the CLI asks for confirmation. Delete is not reversible.

Account and config commands

pagr whoami
pagr logout
pagr config show
pagr config set-key pagr_...
pagr config set-url https://pagr.link

pagr whoami prints the active masked key source, email when available, plan, file count, and worker override when configured. pagr config show respects environment overrides and masks the API key.

Use in CI

Store PAGR_API_KEY as a secret in your CI system.

- name: Publish HTML report
  run: pagr upload output/report.html --title "Nightly report"
  env:
    PAGR_API_KEY: ${{ secrets.PAGR_API_KEY }}

When CI is set, the CLI also prints machine-readable lines:

PAGR_SLUG=...
PAGR_URL=...

Environment variables

• PAGR_API_KEY overrides the locally saved API key.
• PAGR_WORKER_URL overrides the Worker API URL. Default: https://pagr.link.
• PAGR_APP_URL overrides the app URL opened by pagr login. Default: https://app.getpagr.co.
• CI makes upload print PAGR_SLUG and PAGR_URL.

Use with AI agents

Run pagr init in a project to create agent instructions and MCP configuration hints.

pagr init
pagr init --yes
pagr init --no-claude
pagr init --no-mcp

Interactive init asks which assistants you use: Claude Code, Cursor, and Codex. It can write:

• SKILL.md
• .agents/skills/pagr/SKILL.md
• .claude/skills/pagr/SKILL.md
• .cursor/rules/pagr.mdc
• .codex/instructions.md
• .claude/settings.json with the Pagr remote MCP server

Tell the agent to publish the final HTML artifact with pagr upload <file> --title "<title>" and return the public URL.

Troubleshooting

If browser login cannot reach the local callback, run pagr login --manual and paste the generated key. If the CLI says no API key was found, run pagr login, run pagr config set-key pagr_..., or set PAGR_API_KEY. If upload fails with a size or feature error, check the account plan and file size limits.