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 the CLI installs everything in a single operation.

What a component does

When you install a component, the CLI:

1. Reads the component’s manifest (warmhub/manifest.json) to learn what resources it needs
2. Creates shapes for the data types the component works with
3. Sets up subscriptions that trigger actions when data changes or on a schedule
4. Seeds initial data the component needs to operate
5. Creates credential sets for any external API keys the component requires

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: Each installed component has a state that reflects its health:

State	Meaning
ready	All resources exist, all credentials populated
credentials-required	Resources created, but one or more credential keys need values
degraded	One or more declared resources are missing or inactive
paused	All subscriptions paused (via teardown)
installing	Install in progress
error	Install failed

CLI commands

# Install a component from GitHub
wh component install https://github.com/org/my-component --repo myorg/myrepo

# Install from a local path (for development; best for components without subscriptions)
wh component install ./my-component --repo myorg/myrepo

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

# View component details
wh component view my-component --repo myorg/myrepo

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

# Pause all component subscriptions
wh component teardown my-component --repo myorg/myrepo

# Validate a component package offline (no repo needed)
wh component validate ./my-component

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, actions, subscriptions, seeds
  actions/
    summarize/run.sh        # The action script

Installing it:

wh component install https://github.com/myorg/my-summarizer --repo myorg/research
# Installed my-summarizer v1.0.0 [credentials-required]

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

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

Next steps:

• Manifest Reference — full manifest format
• Component Lifecycle — install, update, doctor, teardown
• Authoring Components — build your own
• Sprite Patterns — runtime configuration and debugging
• Testing Components — validation workflow