custom-object-management

Source of truth

hubspot schemas --help is authoritative. Subcommands: list, get, create, update (metadata only), delete (destructive). Schema writes require a private app token with crm.schemas.custom.write. Read bulk-operations/SKILL.md first — every command here uses its JSONL conventions, and schemas delete uses its dry-run / digest / confirm flow.

Discover existing schemas

hubspot schemas list                                       # JSONL: name, label, singular, objectTypeId, source
hubspot schemas list | jq 'select(.source=="custom")'      # custom only
hubspot objects

name is what every other command takes. objectTypeId (e.g. 2-12345678) is only needed for workflow PLATFORM_FLOW targets.

Inspect one schema

Returns the full definition — properties, associations, labels, requiredProperties, primaryDisplayProperty, fullyQualifiedName. Reshape with jq as needed (see bulk-operations/resources/json-patterns.md).

Create a schema

Build a JSON body and pipe it (or pass --file). Minimal valid body:

Add more properties later with hubspot properties create --type <name> ....

Update schema metadata

update patches labels / description only. Property edits go through hubspot properties.

update also supports --dry-run → digest → re-run with --digest --confirm <name> (see bulk-operations/SKILL.md for the pattern).

Delete a schema (destructive)

Schema delete is destructive and irreversible — it permanently removes the schema and every record of that type. It is gated as MetadataDestroy: every delete requires --dry-run first, then re-run with --digest <hash> --confirm <name> within 5 minutes.

Follow the three-step flow documented in bulk-operations/SKILL.md ("Safe destructive workflow"). For schemas, the confirm value is the schema name:

Check hubspot history --since 24h --kind MetadataDestroy to audit recent schema deletes.

Using the schema after creation

Once a schema exists, all hubspot objects ... commands accept its name as --type (e.g. --type pets). Record CRUD, search, association, bulk upsert — all identical to standard objects. Don't re-implement those flows here; see bulk-operations/SKILL.md and crm-lookup.