Pandadoc export

Goal

Drive the pandadoc-export CLI to export all data from the user's PandaDoc account: documents (PDF + JSON), templates (JSON, plus PDF + DOCX via a headless browser), and contacts (JSON), organized per workspace.

How the tool is structured

There are two layers, and they authenticate differently — this matters for how you run them:

• API layer (discover, keys, inventory, extract): uses an Org-Admin API key from .env. Fully unattended.
• Browser layer (templates): exports template PDF + DOCX, which the API cannot produce. It needs a logged-in web session, so the user logs in once in a browser window; the session is then reused headlessly.

Steps

1. Check configuration

Confirm .env exists and contains a real PANDADOC_ADMIN_KEY (an Org-Admin production API key — a regular workspace key cannot list workspaces or mint per-workspace keys). If missing or still a placeholder, copy the example and ask the user to fill it in. Do not proceed without it.

cat .env 2>/dev/null || cp .env.example .env

2. Run the API export

pandadoc-export all

Runs, in order: discover (list workspaces) → keys (generate/reuse a key per workspace; the admin's own workspace is auto-detected and its key reused) → inventory (count docs/templates/contacts) → extract (documents as PDF+JSON by status with folders replicated, templates as JSON, contacts as JSON).

Note: all by itself does not export template PDF/DOCX — that is the browser layer (step 3).

3. Export template PDF + DOCX (browser layer)

Two options:

• As part of everything: pandadoc-export all --with-templates (opens a browser for login first), or
• On its own:

pandadoc-export login        # opens a browser — user logs in to PandaDoc once
pandadoc-export templates    # headless from here on

When a browser window opens, tell the user:

"A browser window has opened — please log in to your PandaDoc account. The session is saved and reused, so you only do this once."

Wait for the user to confirm they logged in. templates auto-recovers across passes if the browser crashes; if the session later expires it stops and prints LOGIN NEEDED — run login again, then re-run templates.

4. Run individual stages (optional)

Goal	Command
List workspaces	pandadoc-export discover
Generate per-workspace keys	pandadoc-export keys
Count items per workspace	pandadoc-export inventory
Download documents + templates(JSON) + contacts	pandadoc-export extract
Skip certain document statuses	pandadoc-export extract --exclude-status voided,draft
Log in for the browser layer	pandadoc-export login
Export template PDF + DOCX	pandadoc-export templates

5. Resume an interrupted run

Every command is idempotent: re-running skips files already on disk and never regenerates an existing workspace key. Just re-run the same command. Recoverable failures are logged to state/errors.jsonl.

6. Verify output

ls output/

Each workspace is a folder named {workspace_name}__{workspace_id}/ containing contacts/, templates/, documents/<status>/..., plus _workspace.json and _manifest.json (expected vs. obtained counts). Template .json, .pdf, and .docx share the same filename stem so they sort together.