GHL CLI

Private HighLevel CLI for full API coverage, secure Private Integration Token auth, raw REST calls, endpoint discovery, and Voice AI setup.

Install

npm install -g ghl-api-cli

For local development from this repository:

npm install
npm run build
npm link

Auth

Preferred auth is a HighLevel Private Integration Token from:

Settings -> Private Integrations -> Create New Integration

PIT auth is the smoothest local path. OAuth is also supported once you have a HighLevel Marketplace app client ID, client secret, redirect URI, and an authorization code from the app install redirect.

Use required scopes for the resources you want. For Voice AI, include:

• voice-ai-agents.readonly
• voice-ai-agents.write
• voice-ai-agent-goals.readonly
• voice-ai-agent-goals.write
• voice-ai-dashboard.readonly

Login:

ghl auth login

This prompts for the Private Integration Token with hidden input, then the location ID.

Non-interactive login:

ghl auth login --token "pit-..." --location-id "LOCATION_ID" --no-verify

Or avoid shell history:

printf '%s' "$GHL_PRIVATE_TOKEN" | ghl auth login --stdin --location-id "LOCATION_ID" --no-verify

Named accounts:

ghl auth login --account agency-a --token "pit-..." --location-id "LOCATION_ID" --no-verify
ghl auth accounts --output json
ghl --account agency-a contacts list
GHL_ACCOUNT=agency-a ghl contacts list
ghl auth logout --account agency-a

Config is stored at ~/.config/ghl-cli/config.json with directory mode 0700 and file mode 0600.

OAuth code exchange:

printf '%s' "$GHL_OAUTH_CLIENT_SECRET" | ghl auth exchange-code \
  --client-id "CLIENT_ID" \
  --client-secret-stdin \
  --redirect-uri "https://your-app.example.com/oauth/callback" \
  --code "AUTHORIZATION_CODE" \
  --location-id "LOCATION_ID"

Refresh later:

printf '%s' "$GHL_OAUTH_CLIENT_SECRET" | ghl auth refresh --client-id "CLIENT_ID" --client-secret-stdin

Env/flag precedence:

1. CLI flags
2. Environment variables
3. Stored config

Supported env aliases:

• GHL_PRIVATE_TOKEN, GHL_TOKEN, GHL_ACCESS_TOKEN, GHL_API_TOKEN, GHL_API_KEY
• GHL_ACCOUNT
• GHL_LOCATION_ID
• GHL_COMPANY_ID
• GHL_BASE_URL
• GHL_API_VERSION
• GHL_OUTPUT
• GHL_TIMEOUT_MS

Full API Coverage

The CLI bundles the 590 endpoint catalog from HighLevel public API coverage. Search it:

ghl endpoints list --search voice-ai --output json
ghl endpoints show create-agent --app voice-ai --output json

Run any catalog endpoint by operationId:

ghl run get-agents --app voice-ai --query locationId=LOCATION_ID
ghl run get-agent --app voice-ai --param agentId=AGENT_ID --query locationId=LOCATION_ID
ghl run create-agent --app voice-ai --data-file agent.json --confirm

Raw escape hatch for any current or future endpoint:

ghl api GET /contacts/ --query locationId=LOCATION_ID
ghl api POST /contacts/ --data-file contact.json --confirm
ghl api DELETE /contacts/CONTACT_ID --confirm

Writes and deletes require --confirm. Use --dry-run to preview.

Voice AI

ghl voice agents list --location-id LOCATION_ID
ghl voice agents get AGENT_ID --location-id LOCATION_ID
ghl voice agents create --data-file agent.json --confirm
ghl voice agents patch AGENT_ID --field welcomeMessage="Thanks for calling" --confirm
ghl voice agents delete AGENT_ID --confirm

Actions:

ghl voice actions create \
  --agent-id AGENT_ID \
  --name "Book appointment" \
  --type "book_appointment" \
  --data-file action-parameters.json \
  --confirm

Call logs:

ghl voice logs list --agent-id AGENT_ID --start-date 2026-06-01 --end-date 2026-06-15
ghl voice logs get CALL_ID

Common Shortcuts

Shortcut groups exist for common resources:

ghl contacts list --query locationId=LOCATION_ID
ghl contacts get CONTACT_ID
ghl opportunities list --query locationId=LOCATION_ID
ghl calendars list --query locationId=LOCATION_ID

Use ghl run or ghl api when shortcut paths differ from the exact API endpoint you need.

Development

npm run typecheck
npm test
npm run build