@getpagr/cli 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MNM Medieproduksjon AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# Pagr CLI
+
+Publish and update HTML files from terminals, scripts, CI, and AI-agent workflows.
+
+One local `.html` file in, one public Pagr URL out.
+
+## Requirements
+
+- Node.js 20 or newer.
+- A Pagr account (optional).
+
+## Installation
+
+Install the npm package globally. The package is `@getpagr/cli`, and the installed terminal command is `pagr`.
+
+```bash
+npm install -g @getpagr/cli
+```
+
+Other package managers:
+
+```bash
+pnpm add -g @getpagr/cli
+yarn global add @getpagr/cli
+```
+
+## Quick Start
+
+```bash
+pagr login
+pagr upload report.html
+```
+
+`pagr upload` prints the public URL, copies it to the clipboard, and opens it in the browser. Use `--no-copy` or `--no-open` to skip either step.
+
+## Latest Authentication Flow
+
+Run `pagr login` to connect the CLI to your Pagr account.
+
+```bash
+pagr login
+```
+
+The default browser flow works like this:
+
+1. The CLI starts a temporary local callback server on `127.0.0.1`.
+2. The CLI opens `https://app.getpagr.co/cli?callback=...&state=...` in your browser.
+3. The Pagr app authenticates you, creates a CLI API key, and posts it back to the local callback.
+4. The CLI validates the `state`, validates that the key starts with `pagr_`, and stores it in `~/.pagr/config.json`.
+5. The login session times out after 5 minutes.
+
+If the browser cannot reach the local callback, the app shows a fallback key. Return to your terminal and run:
+
+```bash
+pagr login --manual
+```
+
+Then paste the key shown in the browser.
+
+## Authentication Alternatives
+
+Paste a key manually:
+
+```bash
+pagr login --manual
+```
+
+Save a key directly without opening the browser or prompting:
+
+```bash
+pagr login --key pagr_...
+```
+
+Save a key through the config command:
+
+```bash
+pagr config set-key pagr_...
+```
+
+For CI and shared scripts, use an environment variable instead of writing local config:
+
+```bash
+export PAGR_API_KEY="pagr_..."
+```
+
+## Configuration File
+
+The CLI stores local configuration at:
+
+```text
+~/.pagr/config.json
+```
+
+The file can contain:
+
+- `apiKey`: your saved Pagr API key.
+- `workerUrl`: an optional Worker/API base URL override.
+
+Environment variables always take precedence over values in `~/.pagr/config.json`.
+
+## Command Reference
+
+### `pagr login`
+
+Authenticate and save an API key to `~/.pagr/config.json`.
+
+Usage:
+
+```bash
+pagr login
+pagr login --manual
+pagr login --key pagr_...
+```
+
+Flags:
+
+- `--manual`: paste an API key manually instead of using browser login.
+- `--key <pagr_...>`: save an API key directly without browser login or prompt.
+
+Behavior:
+
+- Without flags, the CLI asks how you want to log in:
+  - `1. Open browser and log in`
+  - `2. Paste API key manually`
+- Browser login opens `/cli` on `PAGR_APP_URL`, or `https://app.getpagr.co` by default.
+- Keys must start with `pagr_`.
+
+### `pagr upload <file>`
+
+Upload or update an HTML file.
+
+Usage:
+
+```bash
+pagr upload report.html
+pagr upload report.html --title "Weekly report"
+pagr upload report.html --slug weekly-report
+pagr upload report.html --slug weekly-report --title "Weekly report"
+pagr upload report.html --update --slug weekly-report
+pagr upload report.html --inject
+```
+
+Positional arguments:
+
+- `<file>`: required local HTML file to upload.
+
+Flags:
+
+- `-s, --slug <slug>`: use a custom URL slug.
+- `-t, --title <title>`: override the page title.
+- `-u, --update`: force update mode. Fails if the slug or document is not found.
+- `--inject`: write Pagr metadata tags back into the HTML file after upload.
+
+Behavior:
+
+- Reads the file as UTF-8.
+- New uploads call `POST /api/upload`.
+- Updates by `pagr-id` when the HTML contains a Pagr document ID meta tag.
+- Falls back to update by `pagr-slug` when the HTML contains a Pagr slug meta tag.
+- With `--slug`, a custom slug is applied through a metadata update after upload when needed.
+- Copies the final URL to the clipboard on supported systems.
+- When `CI` is set, prints machine-readable `PAGR_SLUG` and `PAGR_URL` lines.
+- On new uploads, the CLI injects `pagr-slug` and, when available, `pagr-id` into the source file when no existing `pagr-slug` is present. Passing `--inject` also writes those metadata tags back into the file.
+
+### `pagr ls`
+
+List published files.
+
+Alias:
+
+```bash
+pagr list
+```
+
+Usage:
+
+```bash
+pagr ls
+pagr ls --limit 20
+pagr list --limit 20
+```
+
+Flags:
+
+- `--limit <count>`: maximum number of files to show. Default: `50`.
+
+Output columns:
+
+- `slug`
+- `views`
+- `plan`
+- `title`
+- `url`
+
+### `pagr rm <slug>`
+
+Delete a published file.
+
+Alias:
+
+```bash
+pagr delete <slug>
+```
+
+Usage:
+
+```bash
+pagr rm weekly-report
+pagr rm weekly-report --yes
+pagr rm weekly-report -y
+```
+
+Positional arguments:
+
+- `<slug>`: required slug to delete.
+
+Flags:
+
+- `-y, --yes`: skip the confirmation prompt.
+
+Behavior:
+
+- Prompts before deletion unless `-y` or `--yes` is passed:
+
+  ```text
+  Delete <slug>? This cannot be undone. [y/N]
+  ```
+
+- Calls `DELETE /api/files/:slug`.
+
+### `pagr config`
+
+Manage local CLI configuration.
+
+Subcommands:
+
+```bash
+pagr config set-key <key>
+pagr config set-url <url>
+pagr config show
+```
+
+#### `pagr config set-key <key>`
+
+Save your API key to `~/.pagr/config.json`.
+
+Arguments:
+
+- `<key>`: required API key. Must start with `pagr_`.
+
+#### `pagr config set-url <url>`
+
+Save a Worker/API base URL override to `~/.pagr/config.json`.
+
+Arguments:
+
+- `<url>`: required Worker/API base URL.
+
+#### `pagr config show`
+
+Print the active configuration.
+
+Behavior:
+
+- Prints a masked API key.
+- Prints the active worker URL.
+- Respects `PAGR_API_KEY` and `PAGR_WORKER_URL` environment variable overrides.
+
+### `pagr init`
+
+Initialize Pagr instructions and MCP config in the current project.
+
+Usage:
+
+```bash
+pagr init
+pagr init --no-claude
+pagr init --no-mcp
+```
+
+Flags:
+
+- `--claude`: create `.claude/skills/pagr.md`. Default: enabled.
+- `--no-claude`: skip `.claude/skills/pagr.md`.
+- `--mcp`: add the Pagr MCP server to `.claude/settings.json`. Default: enabled.
+- `--no-mcp`: skip the MCP config update.
+
+Behavior:
+
+- Always writes `SKILL.md`.
+- With Claude enabled, writes `.claude/skills/pagr.md`.
+- With MCP enabled, updates `.claude/settings.json`.
+- The MCP server command remains:
+
+  ```bash
+  npx -y @pagr/mcp
+  ```
+
+## CI Usage
+
+Store `PAGR_API_KEY` as a secret in your CI system.
+
+```yaml
+- 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, `pagr upload` also prints machine-readable output:
+
+```bash
+PAGR_SLUG=weekly-report
+PAGR_URL=https://uc.pagr.link/weekly-report
+```
+
+## AI-Agent Usage
+
+Run `pagr init` in a project to create agent instructions and Claude Code MCP configuration.
+
+```bash
+pagr init
+```
+
+This writes:
+
+- `SKILL.md`
+- `.claude/skills/pagr.md`, unless `--no-claude` is passed.
+- `.claude/settings.json` with a Pagr MCP server entry, unless `--no-mcp` is passed.
+
+Agents should publish the final HTML artifact with:
+
+```bash
+pagr upload <file> --title "<title>"
+```
+
+They should return the public URL printed by the CLI.
+
+## Environment Variables
+
+- `PAGR_API_KEY`: API key used for authenticated commands. Overrides local config.
+- `PAGR_WORKER_URL`: Worker/API base URL. Overrides local config and defaults to `https://pagr.link`.
+- `PAGR_APP_URL`: app URL opened by `pagr login`. Defaults to `https://app.getpagr.co`.
+- `CI`: when set, `pagr upload` prints `PAGR_SLUG` and `PAGR_URL` lines for scripts.
+
+## Troubleshooting
+
+### No API Key Found
+
+Run one of:
+
+```bash
+pagr login
+pagr config set-key pagr_...
+export PAGR_API_KEY="pagr_..."
+```
+
+### Browser Login Cannot Reach The Callback
+
+Run manual login:
+
+```bash
+pagr login --manual
+```
+
+Paste the fallback key shown in the browser.
+
+### Invalid API Key Format
+
+Pagr CLI keys must start with `pagr_`. Generate or copy a CLI API key from the Pagr app, then run:
+
+```bash
+pagr login --key pagr_...
+```
+
+### Cannot Read File
+
+Confirm the path exists and points to a readable HTML file:
+
+```bash
+pagr upload ./report.html
+```
+
+### Slug Not Found On Update
+
+`pagr upload --update --slug <slug>` only updates files owned by your account. If the file does not exist, upload without `--update` to create a new page:
+
+```bash
+pagr upload report.html --slug weekly-report
+```
+
+### Custom Slug Plan Restrictions
+
+Custom slugs may be plan-gated. If your account cannot use a custom slug, the API returns a plan error. Upload without `--slug` to let Pagr generate a slug.
+
+### Clipboard Copy Not Available
+
+The CLI tries to copy uploaded URLs using platform clipboard tools: `pbcopy` on macOS, `clip` on Windows, and `xclip` or `xsel` on Linux. If no supported clipboard tool is available, the upload still succeeds and the URL is printed.
+
+## Publishing Note
+
+The npm package is:
+
+```text
+@getpagr/cli
+```
+
+The terminal command is still:
+
+```text
+pagr
+```

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+export declare const configCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+//# sourceMappingURL=config.d.ts.map

package/dist/commands/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa,qDA2DxB,CAAA"}

package/dist/commands/config.js

@@ -0,0 +1,63 @@
+import { defineCommand } from 'citty';
+import { readConfig, writeConfig } from '../lib/config.js';
+export const configCommand = defineCommand({
+    meta: {
+        name: 'config',
+        description: 'Manage CLI configuration',
+    },
+    subCommands: {
+        'set-key': defineCommand({
+            meta: {
+                name: 'set-key',
+                description: 'Save your Pagr API key (~/.pagr/config.json)',
+            },
+            args: {
+                key: {
+                    type: 'positional',
+                    description: 'Pagr API key',
+                    required: true,
+                },
+            },
+            run({ args }) {
+                if (!args.key.startsWith('pagr_')) {
+                    console.error('Invalid API key format. Keys must start with "pagr_".');
+                    process.exit(1);
+                }
+                const current = readConfig();
+                writeConfig({ ...current, apiKey: args.key });
+                console.log('API key saved to ~/.pagr/config.json');
+            },
+        }),
+        'set-url': defineCommand({
+            meta: {
+                name: 'set-url',
+                description: 'Override the worker URL',
+            },
+            args: {
+                url: {
+                    type: 'positional',
+                    description: 'Worker URL',
+                    required: true,
+                },
+            },
+            run({ args }) {
+                const current = readConfig();
+                writeConfig({ ...current, workerUrl: args.url });
+                console.log(`Worker URL set to ${args.url}`);
+            },
+        }),
+        show: defineCommand({
+            meta: {
+                name: 'show',
+                description: 'Show current configuration',
+            },
+            run() {
+                const cfg = readConfig();
+                const apiKey = process.env.PAGR_API_KEY ?? cfg.apiKey;
+                console.log('API key:', apiKey ? `${apiKey.slice(0, 13)}...` : '(not set)');
+                console.log('Worker URL:', process.env.PAGR_WORKER_URL ?? cfg.workerUrl ?? 'https://pagr.link');
+            },
+        }),
+    },
+});
+//# sourceMappingURL=config.js.map

package/dist/commands/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE1D,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;IACzC,IAAI,EAAE;QACJ,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,0BAA0B;KACxC;IACD,WAAW,EAAE;QACX,SAAS,EAAE,aAAa,CAAC;YACvB,IAAI,EAAE;gBACJ,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,8CAA8C;aAC5D;YACD,IAAI,EAAE;gBACJ,GAAG,EAAE;oBACH,IAAI,EAAE,YAAY;oBAClB,WAAW,EAAE,cAAc;oBAC3B,QAAQ,EAAE,IAAI;iBACf;aACF;YACD,GAAG,CAAC,EAAE,IAAI,EAAE;gBACV,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;oBAClC,OAAO,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAA;oBACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;gBACjB,CAAC;gBACD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;gBAC5B,WAAW,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;gBAC7C,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAA;YACrD,CAAC;SACF,CAAC;QACF,SAAS,EAAE,aAAa,CAAC;YACvB,IAAI,EAAE;gBACJ,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,yBAAyB;aACvC;YACD,IAAI,EAAE;gBACJ,GAAG,EAAE;oBACH,IAAI,EAAE,YAAY;oBAClB,WAAW,EAAE,YAAY;oBACzB,QAAQ,EAAE,IAAI;iBACf;aACF;YACD,GAAG,CAAC,EAAE,IAAI,EAAE;gBACV,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;gBAC5B,WAAW,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;gBAChD,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;YAC9C,CAAC;SACF,CAAC;QACF,IAAI,EAAE,aAAa,CAAC;YAClB,IAAI,EAAE;gBACJ,IAAI,EAAE,MAAM;gBACZ,WAAW,EAAE,4BAA4B;aAC1C;YACD,GAAG;gBACD,MAAM,GAAG,GAAG,UAAU,EAAE,CAAA;gBACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,MAAM,CAAA;gBACrD,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;gBAC3E,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,SAAS,IAAI,mBAAmB,CAAC,CAAA;YACjG,CAAC;SACF,CAAC;KACH;CACF,CAAC,CAAA"}

package/dist/commands/init.d.ts

@@ -0,0 +1,15 @@
+export declare const initCommand: import("citty").CommandDef<{
+    readonly claude: {
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "Create the Claude Code skill file";
+        readonly negativeDescription: "Skip creating the Claude Code skill file";
+    };
+    readonly mcp: {
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "Create the Claude Code MCP server config";
+        readonly negativeDescription: "Skip creating the Claude Code MCP server config";
+    };
+}>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA8QA,eAAO,MAAM,WAAW;;;;;;;;;;;;;EAmDtB,CAAA"}