intropy int

Authoritative reference for intropy int: scaffolding integrations and reading their scaffold records.

int creates one integration at a time and records exactly what it did. Assembling scaffolded integrations into a System host is intropy sys; browsing the template library before scaffolding is intropy template.

The surface

intropy int create <template> [flags]
intropy int list [dir] [flags]
intropy int show [dir] [flags]

intropy int create

Scaffold a new integration from the official Intropy template library. The positional argument selects which template subdirectory to render (for example hello-world or extractor); run intropy template show <template> first to see its parameters.

Flag	Description
-n, --name <name>	Integration name. Sets the template’s name parameter and, unless --out-dir is set, becomes the output directory.
-o, --out-dir <dir>	Destination directory. Defaults to the kebab-cased --name.
--publishes <message>	Message name the Component publishes. Required by producing templates such as extractor.
--subscribes <message>	Message name the Component subscribes to. Required by consuming templates such as loader.
-s, --set <key=value>	Set a template value. Repeatable.
-f, --values <file>	Values file in YAML/JSON. Repeatable; use - to read one document from stdin.
--no-input	Never prompt; fail if a required value is missing. Required for CI and scripts.
--force	Allow rendering into a non-empty output directory.
--output json	Write the result document to stdout. See Machine-readable result.
--template-repo <owner/repo>	Template library on GitHub. Defaults to templateRepo from configuration, or INTROPY_TEMPLATE_REPO.
--template-version <tag>	Template release tag. Defaults to the latest release.

Note that -o is --out-dir here, not --output; see flag conventions.

Minimal example

intropy int create extractor -n OrderExtractor -o order-extractor \
  --publishes order-placed -s organization=Fluxia -s topic=orders -s empty=false \
  --no-input

fetching integrio-intropy/intropy-templates@v2.0.0
created order-extractor from integrio-intropy/intropy-templates@v2.0.0 (template extractor)
created dependency Contracts from template shared-contracts

--publishes order-placed names the message; the payload type (OrderPlaced) derives from it. -s topic=orders puts the message on a named topic; without it, the topic is the message name. Any required parameter not supplied by -s, -f, -n, --publishes or --subscribes is prompted for interactively; --no-input fails fast instead. A non-empty output directory is refused without --force.

Name and output directory

-n and -o split the same way dotnet new splits them: --name names the artifacts (the .NET project, root namespace, and assembly, so it must be PascalCase), and --out-dir is the literal output location. Without -o, the directory is the kebab-cased name (order-extractor for -n OrderExtractor).

Keep each Component in a kebab-case directory matching its component name. The Aspire System host resolves each component’s project by folder convention: a sibling directory ../<component-name>/src/*.csproj (falling back to a flat <component-name>.csproj). A Component in any other directory is invisible to that convention, and dotnet run in the host fails with No project found for these components by folder convention. The component name is the kebab-cased --name (visible as appId in the scaffold values), so pass -o only with that name.

Dependency auto-scaffolding

Component templates declare a shared contracts library as a dependency, scaffolded as a sibling directory (by convention ../Contracts, from the contracts parameter). The first component to need it creates it; later components find it and skip:

dependency Contracts already scaffolded from shared-contracts — skipped

The dependency is recorded in the component’s scaffold record under dependsOn, and every component references the library via a ProjectReference.

Machine-readable result

--output json writes a result document to stdout, after the human-readable progress lines. Its fields, as captured from a real scaffold:

Field	Contents
template	The template rendered, e.g. "extractor".
owner, repo	The template library, e.g. "integrio-intropy" / "intropy-templates".
version	The exact release tag rendered from, e.g. "v2.0.0".
outputDir	Absolute path of the created directory.
values	The resolved parameter values, including derived ones (appId, port, projectName, payloadType, channel).
dependencies	One entry per auto-scaffolded dependency: its template, absolute outputDir, and action (e.g. "created").

The scaffold record

Every scaffold writes .intropy/scaffold.json inside the new integration. Commit it: later commands read it. int list and int show are views over these records, sys create assembles the System model from them, and manifests derives each component’s workload from them. The record from the extractor scaffolded above:

{
  "schemaVersion": 1,
  "template": "extractor",
  "owner": "integrio-intropy",
  "repo": "intropy-templates",
  "version": "v2.0.0",
  "values": {
    "appId": "order-extractor",
    "businessIncidentsAppId": "business-incident-service.services",
    "channel": "orders",
    "contracts": "Contracts",
    "empty": false,
    "eventSource": "",
    "eventSourceValue": "urn:Fluxia:order-extractor",
    "idempotencyAppId": "idempotency-service.services",
    "name": "OrderExtractor",
    "organization": "Fluxia",
    "payloadType": "OrderPlaced",
    "port": "order-extractor-source",
    "projectName": "OrderExtractor",
    "publishes": "order-placed",
    "topic": "orders"
  },
  "blockKind": "extractor",
  "dataFlow": "in",
  "dependsOn": [
    {
      "template": "shared-contracts",
      "dir": "../Contracts"
    }
  ]
}

Field	Contents
schemaVersion	Record schema version, currently 1.
template, owner, repo, version	The template and the exact library release it was rendered from.
values	The resolved parameter values, including derived ones. A component record names its message and topic but no pub/sub component: sys create assigns the System’s own (<system>-pubsub).
role	On non-component records only: shared-library (the contracts project) or system-host.
blockKind	On component records: the Component’s kind — extractor, loader, or transactional-integration. The field name (and the Block: line in int show output) predates the Component vocabulary and follows it in an upcoming release.
dataFlow	The Component’s direction: in (extractor), out (loader), or both (transactional).
dependsOn	Auto-scaffolded dependencies, each with its template and relative dir.

intropy int list

Walk the directory tree from dir (default: the current directory) and list every project carrying a .intropy/scaffold.json record. Matched projects are not descended into (projects do not nest), and .git, .intropy, node_modules, bin and dist are skipped. Projects with an unreadable record are reported as warnings on stderr without hiding the rest.

Flag	Description
-o, --output <format>	plain (default) or json. The JSON document includes the pinned source and scaffold values.

intropy int list

PATH             TEMPLATE          VERSION
Contracts        shared-contracts  v2.0.0
order-extractor  extractor         v2.0.0
order-flow       system-host       v2.0.0
order-loader     loader            v2.0.0

intropy int show

Show the scaffold record of the integration at dir (default: the current directory, searched upward): which template rendered it, from which release, with which values.

Flag	Description
-o, --output <format>	plain (default) or json. json prints the record unchanged.

intropy int show order-extractor

The first line is the resolved project directory, followed by:

scaffolded from extractor @ integrio-intropy/intropy-templates@v2.0.0
Block: extractor (data flow: in)

Depends on:
  shared-contracts -> ../Contracts

Values:
  appId: order-extractor
  businessIncidentsAppId: business-incident-service.services
  channel: orders
  contracts: Contracts
  empty: false
  eventSource:
  eventSourceValue: urn:Fluxia:order-extractor
  idempotencyAppId: idempotency-service.services
  name: OrderExtractor
  organization: Fluxia
  payloadType: OrderPlaced
  port: order-extractor-source
  projectName: OrderExtractor
  publishes: order-placed
  topic: orders

Removed subcommands

int describe and int local were removed. intropy template show <template> prints what describe printed (a template’s manifest and parameter schema), and intropy manifests render --env local renders what local rendered.