sizmo

Unofficial GoHighLevel CLI — read your CRM + make confirm-gated operational changes from the terminal. Money never moves through it. Not affiliated with HighLevel.

Not affiliated with, endorsed by, or supported by HighLevel. This is an independent open-source tool.

sizmo reads your GoHighLevel location — leads, bookings, pipeline, A/R, money leaks — from the terminal. Write operations (tag, note, opp, appointment, send) require explicit --confirm; without it the CLI prints the exact change and a rerun command, then exits 5. Nothing fires silently. Money stays out — no charges, collections, refunds, or invoice-issuing; payments and invoices are read-only.

Why sizmo

One command answers the only two questions that matter on a Monday — where is money leaking, and who needs me today — and it never invents a number to do it. A blocked data source is reported as unknown, never as zero.

Why not the tools you already have:

• vs the GoHighLevel web UI — the UI makes you click through six screens to assemble what sizmo brief prints in one. And it has no "money leaks" view — overdue receivables and booked-but-never-billed sessions are the numbers it won't surface for you.
• vs the official GHL MCP server — that's an OAuth-app install, multi-tenant, and read-leaning. sizmo is PIT-simple (paste one token, go), does confirm-gated writes too, and is zero-dependency — the whole tool is auditable in an afternoon (see SECURITY.md).
• vs Zapier / Make — those automate tasks on a trigger. sizmo answers questions for a human at a keyboard (and for the agent that human points at it). No per-task pricing, no data routed through a third party — it runs on your machine against your PIT.

It's also built to be piped: every command has a stable --json envelope (API-STABILITY.md), so a human reads the pretty output and their agent consumes the JSON underneath.

Install

Requires Node.js 22+ (current Active LTS).

Option A — npm (recommended):

npx sizmo brief            # run with no install
# or install globally:
npm install -g sizmo
sizmo brief

Option B — clone + install (puts sizmo on your PATH from source):

git clone https://github.com/csalamida07-cyber/sizmo-ghl-cli
cd sizmo-ghl-cli
bash install.sh

install.sh symlinks bin/sizmo.mjs into ~/.local/bin/sizmo. Add ~/.local/bin to $PATH if not already present (the script will warn you if needed).

Option C — clone + run directly:

git clone https://github.com/csalamida07-cyber/sizmo-ghl-cli && cd sizmo-ghl-cli
node bin/sizmo.mjs brief

Then set up a profile. Easiest — guided:

sizmo init

sizmo init walks you through it: it prints the exact GoHighLevel path + the scope copy-block, takes your token from stdin (never argv), writes the profile, and runs sizmo doctor to confirm you're green — all in one run. Agent-drivable too: pipe the token in non-interactively.

echo "pit-yourtoken..." | sizmo init --profile myclient --loc YOUR_LOCATION_ID

Manual alternative:

echo "pit-yourtoken..." | sizmo config set --profile myclient --loc YOUR_LOCATION_ID --pit-stdin

PIT = Private Integration Token. Find it under GoHighLevel Settings > Integrations > Private Integrations. Never pass it as a command-line argument — always pipe it via stdin.

When creating the Private Integration, grant these scopes for the full brief:

contacts.readonly · conversations.readonly · opportunities.readonly
calendars.readonly · invoices.readonly · payments/transactions.readonly

For write commands (tag, note, opp, appointment, send), also add:

contacts.write · opportunities.write · calendars.write · conversations/message.write

Granting fewer is fine — missing scopes show as ⚠ in affected metrics rather than failing the whole command. Run sizmo auth check after setup to see a per-lane scope report.

Auth: PIT vs MCP — sizmo uses a Private Integration Token (PIT), not the GoHighLevel MCP server. See docs/how-to/auth-pit-vs-mcp.md for the comparison and when you'd want each.

Verify auth — or just run the one-shot health check:

sizmo doctor            # scopes + location + CRM model + version, one screen
sizmo auth status
sizmo auth check

sizmo doctor is the "is it me or the tool?" answer: it reports each scope (✓/⚠/✖ with the exact fix line for any blocked one), location reachability + latency, CRM-model freshness, and whether a newer sizmo is available — and it never reports green when a lane is blocked.

Commands

Command list generated from sizmo schema (authoritative — pulled directly from the code):

| Command | Summary | Key flags | |---------|---------|-----------| | sizmo brief | Morning brief — numbers + NEEDS YOU TODAY | --days N (default 7) | | sizmo snapshot | Monday card — 6 metrics, one screen | --days N (default 7) | | sizmo triage | Who is waiting on a reply, longest first | --top N (default 10), --days N (default 30) | | sizmo pipeline | Pipeline health — value by stage + stuck deal sweep | --stuck-days N (default 7), --top N (default 100) | | sizmo noshow | No-show recovery — who to re-book | --days N (default 30), --top N (default 15) | | sizmo receivables | A/R — who owes, how much, how old | --top N (default 20) | | sizmo reconcile | Money reconciliation — collected by source, flags, recurring | --days N (default 30), --top N (default 20) | | sizmo booked-not-paid | Sessions with no invoice or payment — the money leak | --days N (default 30), --top N (default 15) | | sizmo focus | One ranked to-do queue by money at stake | --top N (default 15), --stuck-days N (default 7) | | sizmo segment | Find contacts by criteria — tag, phone, age, etc. | --tag X, --without-tag X, --no-tags, --created-days N, --has-phone, --no-phone, --top N (default 20) | | sizmo crm | Query the local CRM model — counts, lists, staleness | --all (show all items) | | sizmo sync | Refresh the local CRM model (pipelines, calendars, tags, fields, users, location) | [entity] (sync one) |

Writes (confirm-gated)

These commands change data in GoHighLevel. Every write requires --confirm; without it the CLI prints the exact change + a rerun command and exits 5. Nothing fires silently. Money never moves — no charge, collect, refund, or invoice-issue.

| Command | Summary | Required flags | Scope needed | |---------|---------|----------------|--------------| | sizmo tag <contactId> --add <tag> | Add a tag to a contact | --add or --remove | contacts.write | | sizmo tag <contactId> --remove <tag> | Remove a tag from a contact | --add or --remove | contacts.write | | sizmo note <contactId> --text "..." | Add a note to a contact | --text | contacts.write | | sizmo opp create --name --pipeline --stage --contact | Create a pipeline opportunity | --name, --pipeline, --stage, --contact | opportunities.write | | sizmo opp move <oppId> --stage <name> | Move an opportunity to a stage | --stage | opportunities.write | | sizmo opp update <oppId> [--value --status] | Update value or status of an opportunity | --value or --status | opportunities.write | | sizmo appointment book --calendar --contact --start | Book an appointment | --calendar, --contact, --start | calendars.write | | sizmo appointment cancel <apptId> | Cancel an appointment | apptId positional | calendars.write | | sizmo send <contactId> --channel sms\|email --message "..." | Send an SMS or email | --channel, --message | conversations/message.write |

How writes work:

# Step 1 — preview (no --confirm): prints change description + rerun command, exits 5
sizmo tag cid-001 --add VIP --json

# Step 2 — execute (with --confirm): fires the write, exits 0
sizmo tag cid-001 --add VIP --confirm

# --dry-run: shows change description without executing, exits 0
sizmo tag cid-001 --add VIP --dry-run

Pipeline/calendar names are resolved to IDs from the local CRM model. Run sizmo sync first if you've changed stages or calendars.

Utility commands

sizmo init              # guided setup: scopes → token (stdin) → profile → doctor
sizmo doctor            # one-shot health: scopes, location, model, version
sizmo schema            # machine-readable command tree (JSON)
sizmo auth status       # show credential source, location, masked PIT, rotation age
sizmo auth check        # probe live API to verify PIT scopes
sizmo config list       # list all saved profiles
sizmo config use <name> # switch default profile
sizmo config set --profile <name> --loc <id> --pit-stdin
sizmo config rm <name>  # remove a profile
sizmo api /path         # raw GET escape hatch (--paginate --max-pages N)

Global flags (work with every command)

--profile <name>     use a named credential profile
--json               machine-readable output (stable JSON envelope)
--fresh              bypass 60-second read cache — re-fetches live data
--no-cache           alias for --fresh
--no-update-check    skip the once-a-day "newer version available" check for this run

JSON envelope

Every command supports --json. The envelope shape is stable:

{
  "schemaVersion": 1,
  "command": "brief",
  "location": "LOC_ID",
  "data": { ... },
  "degraded": false,
  "warnings": [],
  "cacheAgeMs": 0
}

degraded: true means at least one data source was blocked (scope or auth). Read warnings. A blocked source is not zero — treat it as unknown.

Router verbs differ. init, auth, and config are setup verbs, not data commands — their --json output is a purpose-specific object (e.g. auth check → { lanes, usable }, init → { profile, location, ok, doctor }), not the data/degraded/warnings envelope above. The data commands (brief, snapshot, doctor, …) all use the envelope.

Both contracts are frozen under semver — see API-STABILITY.md for exactly what you can depend on across 1.x (exit codes, JSON shapes, schemaVersion policy, flag names) and what you can't (human output, stderr text, internal modules).

Staying up to date

npx sizmo always runs the latest published version. If you installed globally (npm i -g sizmo), the CLI checks npm at most once a day and prints a one-line nudge to stderr when a newer version exists:

⚠ sizmo 0.9.0 available (you have 0.8.0) — update: npm i -g sizmo@latest

sizmo doctor also shows a CLI VERSION line. The check is privacy-clean: a single GET of the public npm registry, cached 24h, never blocking, nothing sent about you. Turn it off with --no-update-check (per run) or the NO_UPDATE_NOTIFIER / SIZMO_NO_UPDATE_CHECK env vars. It never runs under --json or when output is piped.

Your CRM model

sizmo caches the slow-changing structure of your CRM — pipelines + stages, calendars, tags, custom fields, users, and location — in a local file (~/.config/sizmo/model/<locationId>.json). Recipes read from this cache instead of re-fetching structure on every run.

What it stores: pipeline/stage names + IDs, calendar list, tag list, custom fields, user roster, and location info (timezone, currency, country). Structure only — no contacts, no conversations, no payments.

Sync once, read fast. The model is synced automatically on first use. After that, recipes use the cached copy. Run sizmo sync after you change your pipeline stages or add calendars:

sizmo sync                # full refresh (all 6 entities)
sizmo sync tags           # refresh one entity only

Age is always shown. sizmo crm shows how old each entity is. Stale entries (past TTL: 24h for pipelines/calendars/users/location; 12h for tags/fields) show a warning. The CLI never silently serves stale structure as current.

Model never auto-syncs when stale. It serves the cached data with a loud age banner. This avoids surprise network calls mid-recipe. Use sizmo sync or --fresh to force a refresh.

sizmo crm                 # overview: counts + age per entity
sizmo crm pipelines       # list pipelines + stages
sizmo crm calendars       # list calendars
sizmo crm tags [--all]    # list tags (truncated at 20 by default)
sizmo crm fields          # list custom fields
sizmo crm users           # list users
sizmo crm location        # timezone / currency / country
sizmo crm pipelines --json  # machine output with _meta.source/syncedAt/ageMs/stale

The JSON _meta block in every crm response lets agents branch on staleness without parsing prose:

"_meta": { "source": "cache", "syncedAt": 1718000000000, "ageMs": 3600000, "stale": false, "offline": false }

Scope requirements for a full sync: opportunities.readonly, calendars.readonly, locations/tags.readonly, locations/customFields.readonly, users.readonly, locations.readonly. A 401/403 on one entity marks it blocked; the rest still store. sizmo crm shows ✖ needs <scope> for blocked entities.

Safety model

• Reads are always free. Read commands never change anything in GoHighLevel.
• Writes require explicit --confirm. Tag, note, opp, appointment, and send commands print the exact change + a rerun command and exit 5 (confirmation-required) without --confirm. Nothing fires silently — safe for agent use.
• Money stays out. No charge, collect, refund, or invoice-issue — ever. Payments and invoices are read-only in every path. The only writes are operational: tags, notes, opportunities, appointments, and messages.
• --dry-run available on all writes. Shows the change description without executing. Exits 0.
• PIT never in argv. Credentials are passed via stdin (--pit-stdin) or env var (--pit-env VAR). Never logged, never echoed raw.
• 60-second read cache. Repeated calls within 60s return cached data. cacheAgeMs in the envelope tells you how old. Use --fresh to bypass.

Every claim above is verifiable — see SECURITY.md for the threat model, the self-audit recipes, and how to report a vulnerability. Zero runtime dependencies: what you read is what runs.

Honest limitations

• Rate-limit cap: 5 concurrent requests. The pool is capped at 5 to avoid hammering the GHL API.
• Cache TTL: 60 seconds. Stale data possible within that window. Use --fresh when you need live.
• No-show / booked-not-paid calendar truncation. GHL's /calendars/events endpoint has no pagination cursor. If a calendar returns >= 100 events the result may be silently truncated. A degraded: true warning is emitted in that case.
• Pipeline currency. GHL opportunity monetary values carry no currency field — they inherit pipeline config. The CLI renders them as-is; cross-currency totals are never summed.
• No workflow writes. This tool has no workflow-authoring capability. Workflow creation stays in GoHighLevel's UI.

Exit codes

| Code | Meaning | |------|---------| | 0 | OK | | 1 | API error | | 2 | Usage error (bad flag / unknown command) | | 3 | Auth error / no location resolved | | 4 | Not found (unknown pipeline/stage/calendar name) | | 5 | Confirmation required — rerun with --confirm to execute |

Multi-client

sizmo config set --profile clientA --loc LOC_A --pit-stdin
sizmo config set --profile clientB --loc LOC_B --pit-stdin
sizmo brief --profile clientA
sizmo brief --profile clientB

See docs/how-to/multi-client.md for full workflow.

License

MIT. See LICENSE.

Built by Sizmo — GHL CRM systems & automation. Unofficial; not affiliated with HighLevel.