cto-legends · module specification · infrastructure · v0.3.0
legends-gohighlevel: GoHighLevel CRM, Workflows v3 & 5-Layer Agency Governance CLI
Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.
GitHub Repository (https://github.com/avalonreset/legends-gohighlevel) · Handoff: cto-legends handoff legends-gohighlevel
legends-gohighlevel is a zero-dependency Python 3.11+ CLI that unifies GoHighLevel's two distinct operational HTTP planes into a single deterministic engineering interface: the official Sub-Account API v2 and October 2026 Workflows API v3 plane (services.leadconnectorhq.com via GHL_PIT or GHL_ACCESS_TOKEN) and HighLevel's internal web-app agency governance plane (backend.leadconnectorhq.com via Firebase token-id). Instead of connecting an ambient HighLevel or LeadConnector MCP server that exposes hundreds of unreviewed tools and pulls raw customer PII into model context, legends-gohighlevel provides PII-lean JSON inspection across 20 sub-account resource families, single-command sub-account health audits, and preview-first mutations verified by immediate post-write API readback.
Architecturally, HighLevel enforces sub-account capabilities and agency billing across five independent internal backend layers that sub-account Private Integration Tokens cannot see or modify: Layer 1 (40 location.permissions boolean feature flags), Layer 2 (57 camelCase V1 user boolean switches, 130 of 132 Account Admin V2 scopes, userConfig.assignedToSupported records visibility, and primary email vs. +hubpro alias locationIds synchronization), Layer 3 (Reporting V2 per-dashboard RBAC where Default Dashboards omit account_admin on creation), Layer 4 (two-level agency and location blockAddSmtp Custom SMTP locks), and Layer 5 (SaaS Billing v2 markups across 4 backend stores and 14 metered usage products). legends-gohighlevel resolves active Firebase JWTs read-only from local or remote Chromium LevelDB IndexedDB files (.ldb/.log) without touching SQLite cookie stores, audits all five layers in one pass via live-audit, and enforces canonical SHA-256 plan confirmation before executing any CRM or agency state change.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
A raw Frontier LLM in a browser window—or a static Markdown skill wrapper—has no mechanism to resolve dual-plane HighLevel authentication, avoid undocumented HTTP 422 payload traps on backend.leadconnectorhq.com, or synchronize rebilling markups across four separate HighLevel data stores without dropping state. When an agent guesses HighLevel API calls ad hoc, it routinely triggers HTTP 422 errors on read-only location fields, confuses GET vs. POST DTO keys on Reporting V2 dashboards, or leaves agency wallets exposed to negative Stripe processing margins.
- Dual-Plane Transport & Undocumented DTO Traps: HighLevel's internal backend enforces strict, asymmetric payload contracts: GET /reporting/dashboards/{id}/permissions returns role entries under data.permission, whereas POST requires the array under permissionAccess; PUT /locations/{id} rejects read-only reseller or settings.emailIsvSettings fields with HTTP 422; PUT /users/{id} requires companyId, type, role, and locationIds at the top level; and /conversation-ai/agents/search rejects ?locationId query parameters with HTTP 422 because it infers the tenant from the PIT token. legends-gohighlevel encodes these exact wire schemas in deterministic Python transport code.
- 4-Store & 14-Product SaaS Billing v2 Rebilling Synchronization: Setting a 1.05x (db_markup: 5) Stripe fee shield so a $10.00 wallet reload ($9.41 net after 2.9% + $0.30 Stripe fees) unlocks $9.52 of wholesale usage instead of causing a -$0.59 loss requires synchronizing four distinct endpoints per sub-account: /saas-billing-v2/billing-config/group/{locationId}/{keys} across all 14 metered products (workflow_premium_actions, workflow_ai, conversation_AI, voiceAI, contentAI, reviewsAI, agentStudio, askai, aiStudio, EmailVerification, domainPurchase, whatsApp, emailWarmup, creatorStudio), /saas_service/saas-config/{locationId}/update-twilio-rebilling, PUT /locations/{locationId} (settings.saasSettings), and PUT /saas-api/location-metadata/{locationId}.
- Read-Only IndexedDB JWT Resolution Without Cookie Decryption: Sub-account PIT tokens cannot access backend.leadconnectorhq.com governance endpoints. Rather than extracting or decrypting Chromium's SQLite /profile/Default/Cookies store or calling /oauth/2/login/proxy, BackendClient safely extracts the refreshed 1-hour Firebase JWT (token-id) directly from Chromium's LevelDB IndexedDB (.ldb and .log files) locally or over SSH.
- Hash-Locked Preview-First Mutations with Post-Write Readback: Every write subcommand defaults to writes_sent: 0, snapshotting the live before state, computing the proposed diff, and emitting a canonical sha256 plan hash. Mutations execute only when re-invoked with --apply, target confirmation (--confirm-location or --confirm-user), and --confirm-plan <sha256>, followed by immediate post-write API readback verification.
- PII-Lean Context Guardrails & Live Rate-Limit Telemetry: Unlike ambient MCP servers that dump full contact records and message bodies into LLM context, contacts, conversations, and voice-ai-calls strip personal names, emails, phone numbers, and call transcripts by default (--full requires explicit opt-in) while capturing live X-RateLimit-* headers on every response.
CLI Subcommands & Capability Surface
legends-gohighlevel live-audit | agency-locations | agency-users | user-inspect | pit-list | email-domains — Live 5-Layer Agency Governance Audit: Audits the entire agency across all five backend.leadconnectorhq.com governance layers in a single pass using GHL_TOKEN_ID or Chromium LevelDB IndexedDB extraction. Inspects 40 location feature flags, 57 V1 user boolean switches, 132 V2 user scope capabilities, +hubpro alias location parity, Reporting V2 dashboard RBAC, Custom SMTP locks, dedicated LC Email domains, and masked Private Integration Token inventories.legends-gohighlevel location-unnerf | user-unnerf | user-sync-locations | unlock-dashboards | smtp-unlock | rebilling-sync --apply --confirm-plan <sha256> — 5-Layer Un-Nerf & Rebilling Remediation: Previews and applies deterministic fixes across one or all sub-accounts (--all-locations): enables all 40 location.permissions flags, enables 130 of 132 V2 account admin scopes with assignedToSupported: false, synchronizes locationIds between primary emails and +hubpro aliases, unlocks account_admin: full and account_user: full on default and custom Reporting V2 dashboards, clears agency and location blockAddSmtp locks, and synchronizes 1.05x (--markup 5) rebilling across all 4 stores and 14 SaaS Billing v2 products.legends-gohighlevel subaccount-audit | location | pipelines | opportunities | calendars | calendar-slots | forms | surveys | funnels | tags | custom-values | custom-fields | contacts | conversations — Sub-Account Health Audit & 20-Resource API v2 Inspection: Runs against services.leadconnectorhq.com using GHL_PIT and GHL_LOCATION_ID or named profiles (--profile <name>) in ~/.config/legends-gohighlevel/config.json. subaccount-audit checks CAN-SPAM/A2P business profile completeness, pipelines, open opportunities, published vs. draft workflows, empty custom values, calendars, forms, funnels (--include-redirects), tags, and AI agents, while contacts and conversations default to PII-lean metadata.legends-gohighlevel workflows | workflow-step-types | workflow-inspect | workflow-logs | workflow-validate | voice-ai-agents | voice-ai-calls | conversation-ai-agents | objects | object-records | associations — Workflows API v3, Agent Studio AI & Custom Objects: Inspects workflow lists via API v2 (Version: 2021-07-28) and full workflow step definitions, execution logs, step-type catalogs, and local JSON schema validation via HighLevel's October 2026 Workflows API v3 (Version: v3). Also inspects Voice AI agents, PII-lean Voice AI call logs, Conversation AI agents, Custom Object schemas, custom object records (--object-key), and object associations.legends-gohighlevel custom-value-upsert | custom-value-delete | tag-upsert | tag-delete | contact-upsert | contact-tag | contact-note | opportunity-update | workflow-status — Preview-First Sub-Account CRM & Workflow Mutations: All sub-account write operations run in read-only preview mode by default (writes_sent: 0), returning the current before state, proposed payload, detected action (create, update, or delete), and canonical sha256 hash. Executing the write requires --apply --confirm-location <locationId> --confirm-plan <sha256> and performs immediate post-write API readback verification.legends-gohighlevel rebilling-audit | scope-audit | smtp-audit | dashboard-audit — Offline Governance Calculators & Empire Knowledge Pack: Provides zero-credential offline calculators that model Stripe wallet reload fees (2.9% + $0.30) against db_markup multipliers and generate exact 4-store rebilling sync payloads, V1/V2 user scope catalogs, two-level Custom SMTP unlock bodies, and Reporting V2 permissionAccess payloads. Ships with source-cited Markdown runbooks in wiki/ and an attachable legends.knowledge-pack/v1 vault for legends-empire.
Raw Frontier LLM vs. legends-gohighlevel Execution Matrix
- Agency Permission & Dashboard Governance: Raw LLM (Advises checking sub-account admin checkboxes in the UI; unaware that new sub-accounts leave up to 19 of 40 location flags false and omit account_admin from Default Dashboard RBAC.) vs. Module (Audits and remediates all 5 backend layers via live-audit, location-unnerf, user-unnerf, user-sync-locations, unlock-dashboards, and smtp-unlock.) — Immediate post-write readback against backend.leadconnectorhq.com verifying all 40 location flags, 130/132 V2 scopes, and permissionAccess role arrays.
- SaaS Billing v2 Rebilling & Margin Protection: Raw LLM (Guesses a single billing endpoint or sets 1.00x (db_markup: 0), causing a -$0.59 out-of-pocket agency loss per $10.00 Stripe wallet reload.) vs. Module (Calculates exact Stripe fee shields via rebilling-audit and synchronizes 1.05x (--markup 5) across all 4 HighLevel stores and all 14 metered SaaS Billing v2 products.) — rebilling-status and rebilling-sync verify saas-billing-v2, update-twilio-rebilling, settings.saasSettings, and location-metadata in lockstep.
- CRM & Workflow Mutation Safety: Raw LLM (Issues blind PUT/POST/DELETE calls against live CRM contacts, custom values, or workflows without state snapshots or drift checks.) vs. Module (Default preview mode (writes_sent: 0) emits before state, proposed payload, and canonical sha256 plan hash; requires --apply --confirm-location --confirm-plan.) — Post-write API readback confirms the remote resource matches the proposed mutation and reports verified: true.
- Customer PII & Context Hygiene: Raw LLM (Ambient MCP servers ingest hundreds of tool schemas and dump raw customer names, emails, phone numbers, and call transcripts into LLM prompts.) vs. Module (Zero MCP server; contacts, conversations, and voice-ai-calls return PII-lean metadata by default unless --full is explicitly requested.) — Structured JSON responses include observed_at UTC timestamps, PII-redacted summaries, and live X-RateLimit-* telemetry.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Can sub-account owners use legends-gohighlevel without agency backend access?
- Yes. Sub-account owners only need a sub-account Private Integration Token (GHL_PIT, starting with pit-) and GHL_LOCATION_ID (or ~/.config/legends-gohighlevel/config.json with optional --profile <name>). All 20 sub-account inspection and preview-first CRM mutation commands run directly against services.leadconnectorhq.com.
- Does legends-gohighlevel modify CRM records, workflows, or agency settings immediately?
- No. Every mutation command (custom-value-upsert, custom-value-delete, tag-upsert, tag-delete, contact-upsert, contact-tag, contact-note, opportunity-update, workflow-status, location-unnerf, user-unnerf, user-sync-locations, unlock-dashboards, smtp-unlock, and rebilling-sync) defaults to a read-only preview (writes_sent: 0) that returns the before state, proposed payload, and a canonical sha256 hash. Writes execute only when repeated with --apply and the matching --confirm-plan <sha256>.
- Why does a sub-account show a locked dashboard or missing features even when the user has admin scopes?
- HighLevel enforces permissions across five independent layers: location-level feature flags (location.permissions), user V1 boolean flags and V2 scopes (scopes + userConfig.assignedToSupported), Reporting V2 per-dashboard RBAC (permissionAccess, which omits account_admin on newly created Default Dashboards), two-level Custom SMTP locks (blockAddSmtp), and 4-store SaaS Billing v2 rebilling. Running legends-gohighlevel live-audit inspects all five layers across every sub-account in one pass.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.