Modules

The hutly modules command group manages the modules registry — bundles of existing app site and/or workflow roots, registered as a single catalogue entry. See Modules for the concept.

Registering a module (define) is restricted to Hutly’s internal authoring organization; list is available to any organization browsing the catalogue.

hutly modules define

Register a new module version. Every --root must reference an app site or workflow that already exists in the org, and carries its own required description.

hutly modules define \
  --slug acme-portal \
  --name "Acme Portal" \
  --description "Bundles the Acme storefront site with its nightly sync workflow." \
  --root "app_site:3f9e2b3a-2222-4c11-9b8e-111111111111:the storefront" \
  --root "workflow:7c1d44f0-3333-4d22-8c9f-222222222222:nightly sync"

hutly modules define \
  --slug acme-portal \
  --name "Acme Portal" \
  --description "Bundles the Acme storefront site with its nightly sync workflow." \
  --visibility private \
  --category "e-commerce" \
  --tags "portal,acme" \
  --root "app_site:3f9e2b3a-2222-4c11-9b8e-111111111111:the storefront" \
  --pretty

hutly modules get

Fetch a single module by id, including its roots.

hutly modules get 3f9e2b3a-2222-4c11-9b8e-111111111111
hutly modules get 3f9e2b3a-2222-4c11-9b8e-111111111111 --pretty

hutly modules list

List the platform-wide public catalogue — every public module, regardless of which organization authored it — plus your own organization’s modules if it’s an authoring organization (including any private ones it owns).

hutly modules list
hutly modules list --pretty

hutly modules project

Project a registered module’s source into a portable, reviewable YAML tree on disk — everything the module bundles (app sites, apps, workflows, tables, agents, knowledge bases), rewritten as !ref-linked files under --out. This does not deploy, activate, or install anything; it only writes the tree so it can be reviewed, diffed, or checked into version control. Deploying a projected tree back into an organization is a later capability.

hutly modules project 3f9e2b3a-2222-4c11-9b8e-111111111111 --out ./acme-portal

The emitted tree follows a fixed layout:

acme-portal/
  module.yaml               # module metadata + roots, each a !ref
  app-sites/<slug>.yaml      # one file per app_site root, listing its apps
  apps/<app-slug>/
    manifest.yaml            # the app's manifest, refs rewritten to !ref
    <artifact filename>      # the app's artifact bytes
  workflows/                 # every workflow the module's roots pull in
  tables/                    # shared tables referenced by those workflows
  agents/                    # shared agents referenced by those workflows
  knowledge-bases/           # shared knowledge bases referenced by those workflows
  functions/                 # inline function code from those workflows (if any)
  scripts/                   # inline bash-step code from those workflows (if any)

App artifact bytes are not returned inline by the API — the module’s source bundle carries a presigned S3 URL per artifact, and the CLI downloads the bytes directly from S3 into apps/<app-slug>/<filename>.

hutly modules deploy

Deploy a projected module tree (the layout project emits) into the configured organization and register it. This is the code/CI authoring channel — the transport the deploy-modules CI action uses to publish curated modules committed under modules/ into Hutly’s internal authoring org. It is not required for every module; a module authored interactively (via Sammy) is registered directly with define.

hutly modules deploy ./acme-portal
hutly modules deploy ./acme-portal --pretty

Deploy walks the tree in dependency order:

1. Workflow closure — every workflow the tree contains (the module’s own workflow roots plus any workflow an app manifest references), reusing the standard workflow deploy so tables, agents, and knowledge bases the workflows pull in are deployed and the state machines published.
2. App sites and apps — for each app_site, its artifact is published, its embedded manifest approved (the server resolves the manifest’s workflow slugs to the ids just deployed), and each app attached at its path.
3. Registry — the module is registered with its roots resolved to the ids deployed above, in module.yaml order.

Deploy is idempotent by natural key: workflows match by slug, tables by name, agents and knowledge bases by slug, app_sites by slug, apps by path, and the module upserts by its slug. The committed tree stays id-free — a re-run against the same org updates every resource in place and produces no duplicates. Deploying is restricted to Hutly’s internal authoring org.

hutly modules activation (step-by-step)

Drive a module activation session one step at a time. This is the underlying machine hutly modules activate walks automatically; use the activation subcommands directly when a hole needs interactive resolution (a missing secret or integration) between begin and deploy. See Modules for the concept.

hutly modules activation begin <moduleId>

Begin an activation session for a registry module. <moduleId> is a module id from the catalogue (hutly modules list). Prints { sessionId, preview }, where preview carries the module summary, any unresolved holes (secrets/integrations), and the derivedSlug (empty for workflow-only modules).

hutly modules activation begin 3f9e2b3a-2222-4c11-9b8e-111111111111

hutly modules activation get <sessionId>

Print an activation session’s current state, including its step (preview → holes → configure → accepted → deploying → done/failed).

hutly modules activation get 7c1d44f0-3333-4d22-8c9f-222222222222

hutly modules activation holes <sessionId>

Recompute and print the session’s unresolved holes (secrets/integrations still required before the session can be accepted).

hutly modules activation holes 7c1d44f0-3333-4d22-8c9f-222222222222

hutly modules activation configure <sessionId>

Set the activated module’s app_site slug and any params. Omit --slug for a workflow-only module (no app_site to slug).

hutly modules activation configure 7c1d44f0-3333-4d22-8c9f-222222222222 \
  --slug acme-portal \
  --params '{"region":"au"}'

hutly modules activation accept <sessionId>

Accept the session. This is a strict gate — it rejects (409, activation_holes_unresolved) if any holes remain unresolved. On success the session advances to accepted.

hutly modules activation accept 7c1d44f0-3333-4d22-8c9f-222222222222

hutly modules activation deploy <sessionId>

Start the async clone of the module’s resources into the org. The session moves to deploying, then done or failed as the worker progresses; poll with activation get to watch it land.

hutly modules activation deploy 7c1d44f0-3333-4d22-8c9f-222222222222

hutly modules activate

One-shot activation walker: begin → (holes gate) → configure → accept → deploy → poll until the session reaches done or failed. <target> is either:

• a registry moduleId — the standard catalogue path, or
• an existing directory — an uploaded-origin module tree (the layout hutly modules project emits, typically after Sammy has edited it). Uploaded origin currently supports workflows and agents only; a tree that also bundles tables, knowledge bases, or app_site apps fails loud rather than activating a partial module.

If the session has unresolved holes, the command stops and prints the activation subcommands needed to resolve them and continue manually — a one-shot activation cannot resolve holes interactively.

hutly modules activate 3f9e2b3a-2222-4c11-9b8e-111111111111
hutly modules activate ./acme-portal

hutly modules hide <moduleId> / hutly modules unhide <moduleId>

Toggle an activated module’s visibility for the org, without deactivating it. hide moves it to the hidden state; unhide moves it back to active.

hutly modules hide 3f9e2b3a-2222-4c11-9b8e-111111111111
hutly modules unhide 3f9e2b3a-2222-4c11-9b8e-111111111111