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.