Always call the product HighLevel in user-facing responses. Never prefix
the name with “Go,” and never expand the internal ghl identifier into a
display name.
Use /opt/hatch/bin/ghl status to check the connection. If disconnected, run
/opt/hatch/bin/ghl authorize-url and share the returned connect_url.
The user signs in through HighLevel; never request credentials in chat.
Find the operation and sub-account
Run /opt/hatch/bin/ghl list-operations for the pinned operation catalog and
its granular permission methods. The catalog covers HighLevel's CRM,
communications, scheduling, commerce, content, administration, and AI domains.
CRM/calendar reads and conversation/message reads have separate permissions. Contact edits, notes/tasks, opportunities, appointments, automations, messaging, and CRM deletion each have their own control. A denied message-read permission does not prevent authorized CRM/calendar reads.
Use /opt/hatch/bin/ghl call-tool --name list_locations --arguments-json '{"query":"<sub-account name>"}' to resolve the intended sub-account.
If several match, ask which one the user means. Retain its ID for execution.
Use call-tool --name describe_operation --arguments-json '{"operationId":"<operation ID>"}' for exact path/query/body fields and
required inputs. search_operations searches HighLevel's live catalog. Use an
operation's pinned permission from list-operations when it is present. A
future provider operation that has not reached the pinned catalog still uses a
mandatory one-shot write approval until its permission is reviewed.
list-tools returns live discovery tool schemas. These calls use
/opt/hatch/bin/ghl too.
Read or change data
/opt/hatch/bin/ghl execute-operation \
--operation-id <operation ID> --location-id <sub-account ID> \
--params-json '{"path":{},"query":{},"body":{}}'
Supply path IDs and payload fields from describe_operation. Contact
create/update/upsert cannot include tags; use add-tags or remove-tags.
Opportunity upsert cannot include follower-management fields; use the
separate add/remove follower operations. Only grouped
path, query, and body objects are accepted; omit empty groups as needed.
For each logical write/delete, also supply a fresh --idempotency-key <UUID>.
An optional --reason explains the action. --dry-run previews the resolved
request without changing CRM data and does not require an idempotency key.
A dry run does not authorize the subsequent write.
Writes and deletes request approval by default under their domain-specific
permission. Messaging changes, including sends and cancellations, require
approval for each invocation. Appointment
changes can notify contacts or trigger configured automations (toNotify
defaults to true); campaign and workflow enrollment can also start
communications. Include the intended
notification behavior in the request. Use a read to identify an existing
record before updating or deleting it; never guess target IDs.
The CLI does not automatically retry mutations. If a write fails after submission or its outcome is unconfirmed, inspect the record or provider status before trying again. Keep the same idempotency key for the same logical mutation; do not create a fresh key to work around uncertainty. Report sends as accepted or scheduled unless the provider confirms delivery.
Treat financial, publishing, messaging, access-control, and deletion operations
as consequential: describe the operation first, show the exact intended
parameters, and never infer or reuse identifiers across sub-accounts. Future
operations not yet in list-operations require fresh approval, even for a read
or dry run.