Components

Components are self-contained packages that add functionality to a WarmHub repo. A component declares the shapes, subscriptions, credentials, and seed data it needs, and installation applies the manifest-provisioned resources in one operation. Registered components can also delegate selected resources to a setup callback.

Other uses of “component”

The word component names a few related things. This page covers the installable package — the unit of distribution, defined by component.json and manifest.json. The rest build on it:

• componentRef attribution — tags SDK writes and subscriptions to an installed component by its Org/Name ref.
• Components tab — the web UI view listing a repo’s installed components.
• client.component.* — the SDK methods that install, list, and manage these packages.

What a component does

When you install a component, WarmHub:

1. Reads the component’s manifest (warmhub/manifest.json) to learn what resources it needs
2. Creates manifest-provisioned shapes for the data types the component works with
3. Sets up manifest-provisioned subscriptions that deliver to your webhook endpoints when data changes
4. Seeds initial data the component needs to operate
5. Creates manifest-provisioned credential sets for any external API keys the component requires
6. Asks the component’s setup service to create any setup-managed resources for registered components that declare them

All resources are tracked under a ComponentInstall record so the CLI can manage, diagnose, and tear down the component later.

Key concepts

Manifest-driven: Components use a declarative JSON manifest rather than imperative scripts. The manifest describes what resources the component needs, and the CLI handles creation, reconciliation, and teardown.

Ownership: Resources created by a component are tagged with the component’s ID. This prevents accidental modification and enables clean teardown. Users can still create things under component-owned shapes — ownership protects schema, not data.

State tracking: Installed components expose two distinct state models.

Lifecycle state reflects where the install record sits in its durable lifecycle. The SDK list and get methods (component.list and component.get) return only active installs — installs that have completed successfully and are currently in service. Use wh component doctor or the teardown command to inspect or transition components that are no longer active.

Health state reflects the current condition of the component’s declared resources. The install operation returns a summary health state, and wh component doctor computes a fuller picture that accounts for additional conditions:

Health state	Meaning
ready	All declared resources exist and are active
degraded	One or more declared resources are missing or inactive, subscriptions are in a mixed paused state, there is an ownership conflict, shape drift has been detected, or an error condition exists

Component CLI methods

Installed components can expose their own CLI commands. Once a component is installed, you invoke its methods with:

wh <component-name> <method> --repo <org>/<repo>

For example, if the myorg/my-summarizer component exposes a run method:

wh my-summarizer run --repo myorg/myrepo

These examples assume a repo is specified via --repo. You can omit the flag if you have already set a default repo with wh use or the WARMHUB_REPO environment variable.

Shadowed names: If a component name conflicts with a built-in CLI domain (such as auth or help), the short form is unavailable. Use the explicit fallback instead:

wh component exec <component-name> <method> --repo <org>/<repo>

This form always works regardless of whether the component name shadows a built-in, so it is safe to use in scripts.

Registered components

Registered components are org-owned component identities installed with wh component install <org/name>. Registering publishes the component’s manifest to WarmHub, so installs resolve the stored manifest snapshot directly through the registry. They are useful for sharing a component across repos in an org and for installs that need a setup callback to create external service state.

Authors enable this model by registering the component identity with wh component register <name> --org <org> --manifest <path>, and optionally adding a setupUrl. --source-url is optional documentation metadata. Manifest resources marked provisioning: "setup" are not created by the CLI install path — after WarmHub applies the manifest-managed resources, it asks the component’s registered setup service to create the setup-managed ones.

See Manifest Reference for provisioning and runtimeAccess, CLI Commands for registration commands, and the client.component API reference for the registry methods.

First-party components

WarmHub publishes its own registered components, such as warmhub/identity and warmhub/veritas. You install them by <org>/<name> exactly like any other registered component:

wh component install warmhub/identity --repo myorg/myrepo

There is no separate “install by id” path. A manifest’s reverse-DNS component.id (e.g. com.warmhub.MyComponent) is manifest metadata, not a CLI argument — install and every lifecycle command take the <org>/<name> ref.

CLI commands

# Install WarmHub's first-party Identity component
wh component install warmhub/identity --repo myorg/myrepo

# Validate your package offline, then register it from its manifest and install by <org>/<name>
wh component validate ./my-component
wh component register my-component --org myorg --manifest ./warmhub/manifest.json
wh component install myorg/my-component --repo myorg/myrepo

# List installed components
wh component list --repo myorg/myrepo

# View component details (lifecycle commands take the <org>/<name> ref)
wh component view myorg/my-component --repo myorg/myrepo

# Run health checks
wh component doctor myorg/my-component --repo myorg/myrepo

# Invoke a method exposed by an installed component
wh my-component some-method --repo myorg/myrepo

# Use the explicit form when the component name shadows a built-in CLI domain
wh component exec my-component some-method --repo myorg/myrepo

# Tear down the component (terminal — pauses subscriptions and marks it uninstalled; shapes and data are preserved)
wh component teardown myorg/my-component --repo myorg/myrepo

Example

A component that watches for new Paper things and summarizes them:

my-summarizer/
  warmhub/
    component.json          # Identity: id, name, version
    manifest.json           # Resources: shapes, subscriptions, credentials, seeds

Registering and installing it:

# Register the identity from its manifest, then install by <org>/<name>
wh component register my-summarizer --org myorg --manifest ./warmhub/manifest.json
wh component install myorg/my-summarizer --repo myorg/research
# Installed my-summarizer v1.0.0

# Set the required API key
wh credential set summarizer-creds api_key --value sk-...

# Verify health
wh component doctor myorg/my-summarizer --repo myorg/research

# Invoke a component-defined method
wh my-summarizer run --repo myorg/research

Next steps

Need	Page
The full manifest format (provisioning, runtimeAccess)	Manifest Reference
Install, update, doctor, or teardown an installed component	Component Lifecycle
Build your own component	Authoring Components
The offline validation workflow before publishing	Testing Components
Registration and install commands	CLI: component management