Introduction
Kalup keeps a HubSpot portal's configuration in TypeScript files, and gives your app its types from the same files
Kalup keeps a HubSpot portal's configuration (objects, property groups, properties and custom object schemas) in TypeScript files in your repository. The same files give your app its types, so a renamed property or a removed option fails at compile time instead of in production.
Start here
| You are | Read |
|---|---|
| New to Kalup | Getting started, then How Kalup works |
| An admin looking after one portal, alone or with an agent | One admin, one portal, then Working with AI agents |
| A developer with a sandbox, production and CI | Sandbox, production and CI, Config files, Types and codecs |
| An agency setting up many client portals | Agencies and blueprints |
| An AI agent | Working with AI agents, JSON output, Exit codes, Errors |
What this version does
Version 0.1.0 reads and writes properties and property groups on standard and custom objects. Custom object schemas are read and compared, not written. Pipelines, custom object schema writes and association labels are next. The pull, plan, apply and drift workflow passed live runs on a HubSpot developer test account; other account types are not verified yet, so start on a test account or sandbox. Every command but apply only reads a portal.
| Command | What it does |
|---|---|
kalup init | Create kalup.config.ts and pin the first target, offline |
kalup pull | Read a target and write hubspot/objects/*.ts |
kalup validate | Check the config files and report every issue, offline |
kalup ir | Print the IR document derived from the config files |
kalup fmt | Rewrite the config files in canonical form |
kalup status | Show each target: key, portal check, account, scopes |
kalup compare | Compare config, a target or a snapshot with another |
kalup plan | Show what apply would change on a target |
kalup snapshot | Save one read of a target, with what it covered |
kalup docs | Write a Markdown data dictionary of the config or a snapshot |
kalup apply | Apply a reviewed plan to its target |
kalup rm | Take a property or group out of config and write its tombstone |
kalup state rebuild | Report what a portal holds against its state, and with --write replace the state file |
kalup target rebind | Point a target at a recreated test portal or sandbox |
kalup add | Write a blueprint into the config files |
kalup blueprint upgrade | Merge a new version of a blueprint and keep the client's changes |
apply needs one approval: a person at a terminal, --yes for a small safe change on an unprotected target, or --approve from a reviewed CI job. Every delete needs the person. An edit made in the HubSpot UI is held, not reverted: see Drift.
Every command takes --json and prints one envelope/1 document, with fixed exit codes.
The docs
| Section | What it covers |
|---|---|
| Concepts | How Kalup works, Drift, Targets and credentials, Addresses, Types and codecs |
| Config | Config files and the grammar, kalup.config.ts, Property builders |
| Commands | One page per command: usage, options, output, exit codes and errors |
| Guides | One admin, one portal, Sandbox, production and CI, Agencies and blueprints, Working with AI agents |
| Reference | JSON output, Exit codes, Errors, Network and safety |
Docs as Markdown
Every page is also served as plain Markdown, for agents and scripts:
| URL | Returns |
|---|---|
/docs/<page>.md, for example /docs/commands/pull.md | One page as Markdown |
/docs/<page> with the header Accept: text/markdown | The same Markdown |
/llms.txt | An index of every page with its title and URL |
/llms-full.txt | Every page in one file |
Packages
| Package | What it is |
|---|---|
kalup | The CLI, binary kalup. A dev tool: install it with npm install -D kalup |
@kalup/core | What your config files and app import: builders, codecs, InferProperties, defineConfig and defineRemoved. No dependencies, no network, no file system. Your app imports it at run time: install it with npm install @kalup/core |
Kalup is an independent open-source project maintained by Scopious. It is not affiliated with, endorsed by, or sponsored by HubSpot, Inc. HubSpot is a registered trademark of HubSpot, Inc.