catalog.yaml (embedded catalog)

catalog.yaml is the catalog embedded in the tcli binary. It is the authoritative index of every config artifact category tcli knows about, plus each release’s build settings.

Unlike .tcli.yaml and .tcli.env.yaml, you do not create this file per project. It is part of tcli itself. This page documents it for contributors extending tcli.

The catalog is stored inverted: because ~90% of categories are identical across releases, awBuild and each config artifact category are declared with variants, a set of releases mapped to a script, instead of being repeated under every release. releases is just the supported-release list paired with each release’s C++ standard. tcli assembles this into a per-release view internally, so consumers still see each release’s full build settings and set of categories.

Root

Field	Type	Required	Description
`releases`	map	yes	The supported-release list. Maps a Teamcenter version string (e.g. `"2512"`) to that release’s settings.
`awBuild`	list	yes	Active Workspace build script, as variants. Every release must be covered by exactly one variant.
`configArtifacts`	list	yes	The flat list of every config artifact category. See Config artifact entry.

Release settings

Each entry under releases maps a version to its settings. This map is the supported-release list and doubles as a quality gate for which releases tcli supports.

Field	Type	Required	Description
`cxxStandard`	string	yes	C++ standard (e.g. `"20"`) baked into the generated top-level CMake as `TC_CXX_STANDARD`.

awBuild variant

Each variant maps a set of releases to the Active Workspace build script they use, so a script that spans many releases is written once.

Field	Type	Required	Description
`releases`	list of strings	yes	Releases this variant applies to. Each must exist under `releases`. Every release must be covered by exactly one variant, and no release may appear in more than one.
`script`	string	yes	Path (relative to `assets/`) to the AW build script.

Config artifact entry

Each entry declares one category once. Fields here are shared across every release the category is available in; anything that varies by release lives in a variant.

Field	Type	Required	Description
`type`	string	yes	Stable identity slug for deploy/export routing, CLI args, and asset lookup. Unique across the catalog; never renamed.
`sourceDir`	string	yes	Default project-relative directory for the category’s content.
`lint`	string	yes	Id of the linter applied to this category’s source directory by `tcli lint`. Fixed across releases. Use `none` to opt out. See Linters.
`default`	boolean	yes	Whether a plain `tcli init` scaffolds it. Must be set explicitly (`true` or `false`).
`variants`	list	yes	One or more variants. At least one is required.
`name`	string	no	Friendly display text shown in menus and seeded into a project manifest.
`description`	string	no	One-line explanation shown beneath the name.
`manage`	boolean	no	Whether this category has a tcli Manage authoring step. Defaults to `false`.

name and description are display-only; a project may rename them in its manifest without affecting identity, routing, or lookup, which are all keyed on type.

Variant

A variant maps a set of releases to the release-specific scripts for the category. The union of a category’s variant releases is the set of releases it is available in.

Field	Type	Required	Description
`releases`	list of strings	yes	Releases this variant applies to. Each must exist under the top-level `releases` map. A release must not appear in more than one of a category’s variants.
`deployScript`	string or mapping	no	Deploy script relative to `assets/`. A scalar path, or a mapping with `path` and positional `params`. The path must have a supported script extension.
`exportScript`	string or mapping	no	Export script relative to `assets/`. Same scalar-or-mapping form as `deployScript`.

The 90% of categories that never change ship a single variant listing every release they support. When a script version bumps for newer releases, add a second variant covering just those releases. One variant per script version, not one per release.

Script params

When a script needs positional arguments, use the mapping form and declare its params. Each param becomes a prompt in the TUI and a positional argument in headless mode; values are forwarded to the script by position, in declared order. Params are copied verbatim into a scaffolded project’s manifest.

deployScript:
  path: scripts/workflows/deploy-v1.cmd
  params:
    - name: environment
      description: Target environment
      required: true
      default: dev

Field	Type	Required	Description
`name`	string	yes	Parameter name (prompt label / help text). Unique within a script’s params.
`description`	string	no	One-line explanation.
`required`	boolean	no	A non-empty value must be supplied. Defaults to `false`.
`default`	string	no	Value used when none is supplied.

Script extensions

deployScript and exportScript are optional, but when present the script path must end in a supported extension so tcli knows how to run them:

.cmd, .bat, .ps1

A path with no extension, or an unsupported one, fails catalog validation.

Linters

Linting is code-first, not data-first. Each config artifact category names a linter by a stable lint id, and that id resolves to a Go linter registered in internal/lint. This keeps complex, structure-aware rules in code while the catalog only carries the id.

lint: none opts the category out of linting.
Any other id must resolve to a registered linter, or catalog validation fails.
The id is fixed across releases. It lives on the category, not a variant.

Simple, flat categories reuse the shared FlatNamesLinter (a file-name regex, an allowed-extension set, and an optional file-count cap), registered under an id such as preferences_files. Categories with more complex on-disk layouts get a bespoke linter registered under their own id. Adding a linter is a Register call in internal/lint plus wiring the id into catalog.yaml.

tcli lint runs the linter for each config artifact in a project, skipping the deploy/export scripts that live inside a source directory.

Validation rules

Loading the catalog fails (reporting all violations at once) if:

any release’s cxxStandard is empty.
any release is not covered by an awBuild variant (its build script is empty).
any awBuild variant references a release not declared under releases.
any release appears in more than one awBuild variant.
any configArtifacts[] is missing type or sourceDir.
any configArtifacts[] omits lint (use none to opt out), or names a lint id that is not registered.
any configArtifacts[] omits default (it must be explicitly true or false).
any type is duplicated (two entries collide within a release).
any configArtifacts[] declares no variants.
any variant references a release not declared under releases.
any release appears in more than one variant of the same category.
any deployScript/exportScript has a missing or unsupported extension.
any script declares params without a path.
any param has an empty or duplicated name within a script.

Example

releases:
  "2506":
    cxxStandard: "20"
  "2512":
    cxxStandard: "20"

awBuild:
  - releases: ["2506", "2512"]
    script: scripts/awbuild/awbuild-v1.cmd

configArtifacts:
  # Identical across releases — declared once.
  - type: preferences
    name: "Preferences"
    description: "Teamcenter preference definitions and values."
    manage: true
    sourceDir: configuration/preferences
    lint: preferences_files
    default: true
    variants:
      - releases: ["2506", "2512"]
        deployScript: scripts/preferences/deploy-v1.cmd

  # Only available in one release.
  - type: aw_launcher_tools
    name: "AW Launcher Tools"
    description: "Active Workspace launcher tool definitions."
    sourceDir: configuration/aw_launcher_tools
    lint: none
    default: false
    variants:
      - releases: ["2512"]
        deployScript: scripts/aw_launcher_tools/deploy-v1.cmd

  # Script version bump for newer releases — one variant per version.
  - type: workflows
    name: "Workflows"
    description: "Workflow template definitions."
    sourceDir: configuration/workflows
    lint: none
    default: true
    variants:
      - releases: ["2506"]
        deployScript: scripts/workflows/deploy-v1.cmd
      - releases: ["2512"]
        deployScript: scripts/workflows/deploy-v2.cmd