Map, analyze, and improve your HubSpot CRM
AI building · Agent CLI

Map, analyze, and improve your HubSpot CRM.

Use the HubSpot Agent CLI with Claude or your preferred AI agent to understand how your account is structured, identify practical improvements, and design a safe next step.

Read-only workshop — no CRM changes
StepWorkshop activityWhat you will produce
01Audit and visualizeA focused map of the objects, properties, counts, and relationships your account makes available.
02Analyze and recommendUp to three evidence-based improvements, prioritized by likely impact and effort.
03Explore what comes nextOne safe follow-up workflow with guardrails, prerequisites, and a reusable starter prompt.
One account. Three steps.

Your CRM is the starting point.

Every HubSpot account is different. Work with the objects, data, and permissions available to you. A sparse demo account and a mature production account will produce different—but equally valid—results.

Keep HubSpot read-only throughout the workshop.

Your AI agent may create or update the local workshop HTML file. It must not create, edit, delete, merge, import, associate, enroll, schedule, or preview changes in HubSpot.

Choose an AI agent that has access to a computer and can run terminal commands, open a browser for authentication, and create files in its workspace. Claude Cowork and ChatGPT Codex are two examples.

Use the minimum recommended model configuration.

Choose either GPT-5.5 with High reasoning or Claude Opus 4.8 with High reasoning, based on your preference. A more capable model or higher reasoning setting is also suitable.

Check managed-device and account permissions before the workshop.

Claude Team and Enterprise organizations may need an admin to enable code execution and file creation and allow network access to api.hubapi.com. A HubSpot admin may also need to approve the Agent CLI connection. Review the Agent CLI setup and IT requirements.

01 · Install, authenticate, and add skills

Copy this prompt into the agent workspace you will use for the workshop.

Setup prompt
Install the HubSpot Agent CLI in this agent workspace. If this workspace uses a POSIX shell (macOS, Linux, WSL, or Bash), run `curl -fsSL https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.sh | sh`. If it uses Windows PowerShell, run `irm https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.ps1 | iex`. Then authenticate with `hubspot auth login`, install HubSpot Agent CLI Skills with `npx skills add hubspot/agent-cli-skills`, and use `hubspot --help` to explore what's available.

What to expect: Authentication may pause for browser approval. A sandboxed agent workspace may use a one-time authorization code instead of a localhost callback; complete that exchange only in the same trusted agent session and never share an access token. Some agent shells also require the CLI’s PATH instruction to be reused for later commands.

02 · Confirm your setup

After Step 1 finishes, paste this single follow-up prompt. It summarizes the evidence already returned and checks only what is still missing.

Confirmation prompt
Using the results from the setup you just completed, return a Partner Day readiness check. Reuse the evidence already available. Do not rerun a command or create a test file unless evidence for an outcome is missing. Do not reinstall the HubSpot Agent CLI, repeat authentication, reinstall the HubSpot Agent CLI Skills, or repeat `hubspot --help` as part of verification.

Confirm these three outcomes:

1. CLI ready: report the installed version and confirm that `hubspot --help` returned the available command surface.
2. HubSpot connection ready: report the authenticated user and intended HubSpot account and portal ID. If browser approval or a one-time authorization-code exchange is still pending, mark this outcome `Needs attention`. Never display an access token.
3. Agent workspace ready: confirm that HubSpot Agent CLI Skills are installed, local file creation is available, and any PATH instruction needed across separate shell calls is clearly stated.

Return exactly one short checklist with `Ready` or `Needs attention` for each outcome, followed by one overall status. If evidence is missing, run only the minimum read-only check needed to confirm it. If something still needs attention, give one specific recovery action and stop. Do not inspect CRM records or make any changes in HubSpot.
01
Audit and visualize

Create your HubSpot Account Map

Build a focused, read-only view of the CRM structure your agent can verify.

Your goal

Create a current-state map that adapts to your account. The result should be useful whether your portal is mature, custom-object-heavy, permission-limited, or nearly empty.

Copy/paste prompt
Continue in the same agent workspace from the completed Setup verification. Reuse the account, portal ID, and CLI readiness already confirmed there. Do not repeat installation, authentication, skills installation, or `hubspot whoami`. If Setup verification did not finish with an overall `Ready` status, stop and tell me to ask a workshop facilitator for help.

Use the HubSpot Agent CLI and any installed HubSpot Agent CLI Skills to create a focused, read-only account map. If you are unsure about a command, inspect `hubspot --help` instead of guessing.

Build the map:

1. Discover the CRM object types available to this account.
2. Choose up to five business-relevant objects for the map. Prioritize accessible objects that contain data and include up to two custom objects when available. Adapt to this account instead of assuming which objects or HubSpot products it uses.
3. For each selected object, report its display name, internal type, record count or "not verified," and two or three notable properties based only on returned metadata. Identify standard or custom objects only when the CLI provides that evidence.
4. Verify up to three meaningful relationships between the selected objects. Prefer relationship metadata supported by the current authentication. If a metadata command rejects the current OAuth credentials, do not bypass it or ask for another credential. Use the smallest read-only record sample needed to check real associations, retrieving only record IDs and association metadata—not property values. State the evidence method and sample size. Treat an inconclusive check as "not verified."
5. Create a concise visual map in a self-contained file named `hubspot-account-map.html`. Show every selected object as a node, even when no relationship is verified. Draw no more than three relationship edges, and draw an edge only when the CLI returned supporting evidence. If you cannot create local files, return the same map as a Markdown table and text-based relationship diagram.

Follow these guardrails:

- Use only read operations through the Agent CLI. Do not change or preview changes to HubSpot.
- Prefer metadata and record counts over record retrieval. Do not export complete record sets or display sensitive property values, credentials, or the authenticated user's email in the artifact.
- Treat inaccessible information as "not verified," not absent. Continue with whatever evidence the account and permissions make available.
- Do not infer subscriptions or product adoption from object availability alone.
- Stop after documenting the current state; do not recommend changes yet.

Your HubSpot Account Map must include:

1. The account name or label already confirmed during setup, if available, and the portal ID—without rerunning a connection check.
2. A focused object inventory with record-count status and property highlights.
3. A visual map containing every selected object and only verified relationship edges.
4. A "What I could not verify" section for permissions, evidence gaps, and the relationship-verification method used.
5. Confirmation that you used read-only Agent CLI operations and made no CRM changes.

When the map is complete, show me the file location if you created one, give me a three-bullet summary, and wait for the next workshop step.

What success looks like

  • Your agent reuses the portal confirmed during setup instead of repeating connection checks.
  • The visual shows no more than five relevant objects and three verified relationship edges.
  • Unknown or inaccessible details appear as “not verified,” with the evidence method explained.
  • The agent confirms it made no CRM changes or exposed sensitive values.
02
Analyze and recommend

Turn the map into priorities

Identify improvements that the available evidence supports—without changing HubSpot.

Your goal

Use the map to find a small number of practical improvements. Prioritize clarity and evidence over a long list of generic best practices.

Copy/paste prompt
Continue from the HubSpot Account Map you created in Step 1. Analyze that verified current state and recommend practical improvements for this account.

Remain read-only. Do not create, edit, delete, merge, import, associate, enroll, schedule, or preview any changes in HubSpot. You may use up to three additional targeted read-only Agent CLI data checks only when they resolve an important evidence gap. A help lookup for command syntax does not count as a data check. Before each data check, name the uncertainty it will resolve, and stop checking once the available evidence is sufficient. Prefer metadata, counts, and aggregate results; do not expose sensitive record values.

Create up to three supported recommendations. Fewer than three is correct when the evidence does not support more. If no change is well supported, recommend a read-only validation step instead of inventing a problem.

1. Start with a specific observation from the account map.
2. Separate verified evidence from interpretation. Label incomplete evidence as an assumption or "not verified."
3. Explain the likely business or operational impact in plain language. If the impact depends on unverified business intent, label it as potential—not confirmed.
4. Recommend one proportionate improvement. Prefer a read-only validation step when the underlying gap or business need is not yet verified. A read-only validation step may use ad hoc Agent CLI queries and return results in chat or a local file; it must not create or save a HubSpot report, list, view, dashboard, workflow, or other portal asset.
5. Rate its likely impact and implementation effort as Low, Medium, or High.
6. State the confidence level and what someone should verify before acting. Do not assign High confidence when the conclusion depends on unverified business intent.

Use these evidence rules:

- An empty object, zero count, or missing association is not automatically a gap; it may be intentional.
- Do not infer subscriptions, feature adoption, team behavior, business model, intended process, or business need from an object or property name, availability, or count alone.
- Call something a gap only when verified account evidence indicates that an intended outcome or existing process is not being met.
- Put a potentially useful but unverified idea under "Open questions," not in the ranked recommendations. Include no more than two open questions.
- It is valid to conclude that the checked areas appear healthy.

Adapt the analysis to the account. Consider data quality, CRM structure, lifecycle or process consistency, relationship coverage, and reporting readiness only when the map provides relevant evidence. If this is a sparse demo account, recommend foundational setup or validation steps instead of inventing problems.

Rank only the supported recommendations, using this order:

- Strongest evidence of a real problem or useful measurement first.
- Higher likely impact first when evidence strength is similar.
- Lower effort first when evidence strength and impact are similar.

Update `hubspot-account-map.html` with a new section named "Analysis and recommendations." Preserve the existing map. Add a compact priority table containing: rank, verified observation, evidence, likely impact, recommendation, effort, confidence, and verification needed. If conditional opportunities remain, place up to two of them in a separate "Open questions" list outside the ranking. If no local file exists, return the section in Markdown instead.

When complete, show me the updated file location, summarize the highest-priority supported recommendation or validation step in two sentences, confirm that you made no CRM changes, and wait for the next workshop step.

What success looks like

  • You have no more than three supported priorities—and fewer when the evidence is healthy.
  • Empty objects and suggestive names are not treated as proof of a business gap.
  • Unverified opportunities appear as open questions or read-only validation steps, not ranked conclusions.
  • Read-only validation uses ad hoc CLI queries and local output—not saved HubSpot assets.
  • The original map remains intact and no CRM data changed.
03
Explore what comes next

Design a safe follow-up workflow

Turn one recommendation into a reusable next step you can validate after the workshop.

Your goal

Explore what an agent-assisted follow-up could look like without creating the automation, scheduling a task, or changing CRM data today.

Copy/paste prompt
Continue from the Account Map and recommendations you completed in Steps 1 and 2. Choose the highest-priority recommendation that is both useful and sufficiently supported by evidence, then design one safe follow-up workflow someone could validate after this workshop. Reuse only the evidence already present in the artifact; do not run any new Agent CLI or other data checks during this step.

This is a planning exercise only. Do not create or schedule an automation. Do not create, edit, delete, merge, import, associate, enroll, or preview changes in HubSpot. Do not assume that a feature, permission, integration, or subscription is available; mark each prerequisite as "verified" or "needs verification." Preserve the evidence labels from Step 2: do not turn a conditional opportunity into a confirmed problem or infer a business model, intended process, or operational purpose from object names, counts, or relationships alone.

Design the workflow with these parts:

1. Outcome: the practical result the workflow should produce.
2. Starting point: the schedule, event, file, or human request that would begin it.
3. Read-only inputs: the minimum HubSpot metadata or records it would need.
4. Decision logic: how it would turn those inputs into a useful result.
5. Output: a report, draft, alert, or proposed action. Default to an output outside HubSpot.
6. Human checkpoint: what a person must review before any CRM write or external communication.
7. Guardrails: scope limits, privacy considerations, failure conditions, and how to prevent unsupported assumptions.
8. Prerequisites: required access, tools, data, or HubSpot capabilities, each labeled "verified" or "needs verification."
9. Success signal: one observable way to decide whether the workflow is useful. It must remain valid when the result shows no problem; success cannot require finding a defect or opportunity.

Classify every operation the workflow actually proposes as one of the following. Do not add setup checks, discovery commands, or hypothetical operations just to populate the classification:

- READ: retrieves information without changing HubSpot.
- DRAFT: prepares an output or proposed action for human review.
- WRITE: would change HubSpot or contact someone and therefore requires separate approval outside this workshop.

Create a reusable starter prompt for a future test run. The starter prompt must default to READ and DRAFT operations, begin with a dry run, stop before any WRITE operation, and require explicit human confirmation before proceeding beyond the plan.

Update `hubspot-account-map.html` with a final section named "What comes next." Include the workflow outline, operation classifications, prerequisites, guardrails, success signal, and reusable starter prompt. Preserve the existing sections and add exactly one "What comes next" section. Before finishing, perform a local privacy sweep of the complete artifact: remove the authenticated user's email and ensure no credentials, sensitive property values, or unnecessary personal data appear. If no local file exists, return the section in Markdown instead.

Finish with a concise, factual recap of what the account map revealed, the recommended priority, and the proposed follow-up workflow. Preserve all "potential," "not verified," and conditional labels; do not describe an inferred business process as fact. Confirm that you ran no new data checks, did not create or schedule an automation, and made no CRM changes.

What success looks like

  • The workflow addresses one supported recommendation from Step 2 without running new data checks.
  • Every operation is classified as READ, DRAFT, or WRITE.
  • A human checkpoint blocks CRM changes and external communication.
  • The success signal remains useful even when the workflow finds no problem.
  • The plan preserves evidence labels, names its prerequisites and safeguards, and claims no unavailable features.
  • The final artifact omits the authenticated user's email, credentials, sensitive values, and unnecessary personal data.
The CLI is not authenticated

Ask a facilitator to help reconnect the intended account. Never paste an access token or credential into your AI chat.

You do not have enough access

Pair with someone at your table or follow the presenter’s example. Treat inaccessible information as “not verified.”

The account has little or no data

Continue with accessible object and property metadata. Foundational recommendations are valid for a sparse demo account.

The agent treats missing data as a business gap

Ask it to move the idea to “Open questions” unless the evidence proves an intended outcome is unmet. A valid workflow result may find no problem.

The agent tries to make a change

Stop it and repeat: “Use read-only Agent CLI operations. Do not preview or make any HubSpot changes.” A saved report, list, view, dashboard, or workflow also counts as a change.

A command fails

Ask the agent to inspect hubspot --help and adapt to the installed command surface instead of guessing.

The HTML file cannot be created

Continue in Markdown. The evidence and reasoning matter more than the output format.

Authentication pauses for a code

Complete the browser approval and return the one-time authorization code only to the same trusted agent session that requested it. Never share an access token.

The agent cannot find hubspot later

Ask it to reuse the CLI path or PATH instruction reported during setup. Do not reinstall the CLI.

Your final deliverable

One account-specific action plan

Your finished hubspot-account-map.html combines a verified CRM map, up to three prioritized improvements, and one safely bounded follow-up workflow. The artifact can vary by account; the evidence standard does not.

HubSpot Partner Enablement · Agent CLI workshop · Read, reason, then plan.