HubSpot Workflow Documenter

Documents a HubSpot portal's workflows and finds what is broken in them: overlapping enrollment, dead email, form and list references, unreachable actions. Plain-English descriptions and a Mermaid diagram per workflow. A read-only Claude skill that issues GET requests only and never creates, edits or deletes anything.

Why it exists

Agencies inherit portals with hundreds of workflows and no documentation. Nobody has written it, because writing it by hand is miserable and the portal changes underneath you. This produces it in one pass, and the findings section tells you what is actually wrong.

Install

Requires Python 3.9 or later. No dependencies.

Zero install, straight from a clone:

git clone https://github.com/meticulosity/hubspot-workflow-documenter.git
cd hubspot-workflow-documenter
PYTHONPATH=src python3 -m workflow_documenter --dry-run --out output/sample.md

That last command produces a complete sample document from bundled fixtures without touching the network or needing a token, so you can see the output before granting any access.

Or install it properly, which also gives you the hubspot-workflow-documenter console script:

pip install .
hubspot-workflow-documenter --dry-run --out output/sample.md

pip install . pulls in nothing: this project has no dependencies.

Use it against a real portal

See SETUP.md for the private app and its scopes.

export HUBSPOT_TOKEN='pat-na1-...'
PYTHONPATH=src python3 -m workflow_documenter --out output/portal.md

(or hubspot-workflow-documenter --out output/portal.md if you used pip install .)

Options:

Flag Effect
--out FILE output path, default output/workflows.md (git-ignored)
--dry-run render from fixtures, no network
--from-dir DIR read exported JSON instead of the API
--include-webhook-urls show full webhook URLs (they are credentials)

Read only, and how to check

HubSpot has no read-only scope for workflows. Any token that can read a workflow can also delete one, so "the token cannot write" is not a promise anyone can make. This is what we do instead:

  • One module, src/workflow_documenter/http.py, opens a socket. It raises on any method except GET.
  • The single exception is the token introspection call, which HubSpot exposes only as a POST and which reads nothing but the token's own scope list.
  • tests/test_no_writes.py parses the source and asserts no other module can import urllib, and that http.py contains exactly one write-method literal.

Run PYTHONPATH=src python3 -m pytest tests/test_no_writes.py -v before you trust it.

Licence

MIT.