Configuration Reference

This page is the single reference for all configuration files used in tSM packaging and deployment. It covers:

• package.yaml — package definition (per package)
• tsm-project.yaml — project-level workspace settings
• ~/.tsm/ — user-level CLI configuration and credentials

These files follow the same layered model found in many enterprise development platforms: project-level settings live in the repository and are shared via Git, while user-level settings (credentials, personal preferences) live in the home directory and are never committed.

See also:

• Configuration Packages
• Installation Artifacts
• tSM CLI

---

Workspace layout

A complete workspace has this structure:

tsm-project.yaml                    # project-level settings (committed to Git)

packages/
  core-common/
    package.yaml                  # package definition
    shared/                       # content area
      Register/                   # entity-type subfolder (auto-generated)
      Script/
      Form/

  ordering-sdwan/
    package.yaml
    sdwan-product/
      EntityCatalogCategory/
      EntityCatalogSpecification/
      Characteristic/
      Form/
    sdwan-fulfillment/
      Process/
      Script/

~/.tsm/                           # user-level settings (NOT committed)
  config.json                     # CLI user preferences
  credentials.json                # stored environment credentials

Key rules:

• tsm-project.yaml is committed to Git — it defines the project for all team members.
• packages/*/package.yaml files are committed to Git — they define each package.
• ~/.tsm/ is user-local. It is never committed. Each developer has their own credentials and defaults.
• Entity-type subfolders inside package areas are created automatically by tSM Studio during sync.

---

package.yaml

The package definition file. One per Configuration Package. Located at:

packages/<packageId>/package.yaml

Full example

packageId: ordering-sdwan
name: Ordering / SD-WAN
version: 1.4.0
description: SD-WAN-specific ordering configuration.
ownerTeam: SDWAN

dependencies:
  - packageId: core-common
    versionRange: ">=1.0.0 <2.0.0"
    kind: required

  - packageId: ordering-core
    versionRange: ">=1.2.0 <2.0.0"
    kind: required

areas:
  - id: sdwan-product
    path: sdwan-product
    description: SD-WAN commercial and product-model configuration.
    configTypes:
      - code: cap.ordering.sdwan.product
        includeSubtree: true

  - id: sdwan-fulfillment
    path: sdwan-fulfillment
    description: SD-WAN-specific process and orchestration configuration.
    configTypes:
      - code: cap.ordering.sdwan.fulfillment
        includeSubtree: true
    entityRules:
      - entityType: Script
        include:
          - idOrCode: SDWAN.EligibilityCheck

policy:
  managed: true
  allowDelete: false
  enforceDependencies: true

Package (top-level fields)

Field	Type	Required	Description
packageId	String	Yes	Stable unique identifier. Should match the directory name.
name	String	Yes	Human-readable name shown in Studio and CLI output.
version	String	Yes	Package version. Semantic versioning recommended (1.4.0).
description	String		Human-readable purpose of the package.
ownerTeam	String		Team responsible for this package.
dependencies	List<Dependency>		Other packages this package requires.
areas	List<Area>	Yes	Content areas inside the package.
policy	Policy		Install and upgrade behavior.

Dependency

Field	Type	Required	Description
packageId	String	Yes	Package ID of the required dependency.
versionRange	String	Yes	Allowed versions (e.g. >=1.2.0 <2.0.0).
kind	Enum	Yes	required — must be installed. optional — advisory.

Version range syntax

Version ranges follow standard semver range notation:

Range	Meaning
>=1.0.0 <2.0.0	Any 1.x version.
>=1.2.0 <1.3.0	Any 1.2.x patch.
>=0.0.1 <1.0.0	Any pre-1.0 version.
>=2.0.0	Version 2.0.0 or later (no upper bound).

Area

Field	Type	Required	Description
id	String	Yes	Stable area identifier. Used in CLI and API references.
path	String	Yes	Relative directory path inside the package (default: same as id).
name	String		Optional display name.
description	String		What this area contains.
configTypes	List<AreaConfigType>	Yes	ConfigTypes that define the area scope.
entityRules	List<EntityRule>		Optional per-entity-type refinements.

An area should represent a business or configuration area (e.g. sdwan-product, ticketing-flow, shared), not a technical entity type. Entity-type subfolders are created automatically by Studio during sync.

AreaConfigType

Field	Type	Required	Description
code	String	Yes	ConfigType code used as the selection root.
includeSubtree	Bool	Yes	true — include all descendant ConfigTypes. false — exact match.

Example

configTypes:
  - code: cap.ordering.sdwan.product
    includeSubtree: true

This matches cap.ordering.sdwan.product and any descendant such as cap.ordering.sdwan.product.access.

EntityRule

Optional refinements per entity type within an area. Only needed for edge cases.

Field	Type	Required	Description
entityType	String	Yes	Entity type this rule applies to (e.g. Form, Process).
include	List<Selector>		Items to include regardless of ConfigType matching.
exclude	List<Selector>		Items to exclude even if ConfigType matches.
filters	List<Filter>		Additional filters on top of ConfigType selection.

If no entityRules are specified, the area includes all entity types matching the ConfigType scope. Only add entity rules when you need to override the default behavior (e.g. explicit includes, excludes, or filters for a specific entity type).

Each include / exclude entry is a Selector object with one field:

Field	Type	Required	Description
idOrCode	String	Yes	Entity identifier. If a UUID, treated as ID; otherwise treated as business code.

Prefer codes over UUIDs.

entityRules:
  - entityType: Script
    include:
      - idOrCode: SDWAN.EligibilityCheck

Filter

Narrows selection further within one entity type.

Field	Type	Required	Description
field	String	Yes	Entity field to filter on (for example name, status, register.code).
op	String	Yes	Filter operator aligned with Public API semantics, e.g. eq, noteq, gt, gte, lt, lte, contains, notcontains, startswith, endswith, in, notin, empty, notempty, btw.
value	String	Yes	Operator value. For list/range operators, use comma-separated values (for example ACTIVE,PENDING or 100,500).

Filters map to the same API filtering model used by /search and /page: field__operator=value.

filters:
  - field: name
    op: contains
    value: sdwan

  - field: status
    op: in
    value: ACTIVE,PENDING

Policy

Controls install and upgrade behavior.

Field	Type	Required	Default	Description
managed	Bool		true	Installed items are tracked as managed by this package.
allowDelete	Bool		false	If true, items missing from the package are deleted on install/upgrade.
enforceDependencies	Bool		true	Required dependencies must be satisfied before installation.

Effective selection logic

For each area, the selection works as follows:

1. Start with all items whose configType matches one of the area's ConfigTypes.
2. When includeSubtree: true, include descendant ConfigTypes.
3. If entityRules are present, apply per-entity-type overrides (include, exclude, filters).
4. Store results into the area directory, grouped by entity type in auto-generated subfolders.

---

tsm-project.yaml

The project definition file. One per workspace. Located at the workspace root:

tsm-project.yaml

This file defines project-wide settings that apply to all team members. It is committed to Git.

Full example

name: acme-bss
description: ACME BSS solution — ordering, CRM, ticketing, and SD-WAN overlay.

sourceDirectory: packages

packages:
  - path: packages/System
  - path: packages/InfraCommon
  - path: packages/BSSBase
  - path: packages/OSSBase
  - path: packages/TicketingBase
  - path: packages/SDWAN

environments:
  dev:
    url: https://dev.tsm.example.com
    description: Shared development environment.
  test:
    url: https://test.tsm.example.com
    description: Integration testing.
  prod:
    url: https://tsm.example.com
    description: Production.

plugins:
  - id: tsm-studio-spel
    enabled: true
  - id: tsm-studio-tql
    enabled: true

Project (top-level fields)

Field	Type	Required	Description
name	String	Yes	Project identifier. Used in CLI output and Studio UI.
description	String		Human-readable project description.
sourceDirectory	String		Root directory containing packages (default: packages).
packages	List<PackageReference>		Explicit list of packages in this project.
environments	Map<String, Environment>		Named environments available to all team members.
plugins	List<PluginConfig>		Studio plugin configuration.

PackageReference

Field	Type	Required	Description
path	String	Yes	Relative path to the package directory.

If packages is omitted, Studio auto-discovers packages by scanning sourceDirectory for directories containing package.yaml.

Environment

Field	Type	Required	Description
url	String	Yes	Base URL of the tSM instance.
description	String		Human-readable environment description.

Environments defined here are available to all team members. They appear in tsm auth list and can be used with --target-env.

Individual credentials for these environments are stored in the user-level ~/.tsm/credentials.json — never in the project file.

PluginConfig

Field	Type	Required	Description
id	String	Yes	Plugin identifier.
enabled	Bool		Whether the plugin is active (default: true).

---

~/.tsm/ (user home directory)

The user-level configuration directory. Located at:

~/.tsm/
  config.json         # CLI user preferences
  credentials.json    # stored environment credentials

These files are never committed to Git. Each developer has their own copy.

On first use, the CLI creates ~/.tsm/ with restricted permissions (700).

---

~/.tsm/config.json

Stores CLI user preferences and per-project defaults. Managed via tsm config set / tsm config get.

Full example

{
  "output": "table",
  "timeout": 300,
  "color": true,
  "pager": true,
  "default-env": "dev",
  "projects": {
    "acme-bss": {
      "default-env": "test",
      "output": "json"
    }
  }
}

Top-level keys are global defaults. The projects map contains per-project overrides keyed by the project name from tsm-project.yaml. When resolving a setting, the CLI checks projects.<current-project> first; if the key is absent it falls back to the top-level value.

Settings reference

Key	Type	Default	Description
output	String	table	Default output format: table, json, or yaml.
timeout	Integer	300	HTTP request timeout in seconds.
color	Bool	true	Enable colored terminal output.
pager	Bool	true	Pipe long output through the system pager.
default-env	String	—	Target environment alias (e.g. dev, test, prod).
projects	Object	{}	Per-project overrides keyed by tsm-project.yaml name. Each entry can contain any of the keys above.

All settings can be overridden per-command using flags or environment variables:

Setting	Flag	Environment variable
output	--output	—
timeout	--timeout	—
color	--no-color	NO_COLOR
default-env	--target-env	TSM_ENV

---

~/.tsm/credentials.json

Stores authentication credentials for tSM environments. Managed via tsm auth login / tsm auth logout.

The file is created with restricted permissions (600).

Full example

{
  "environments": {
    "dev": {
      "url": "https://dev.tsm.example.com",
      "auth": "basic",
      "user": "admin",
      "password": "encrypted:v1:...",
      "addedAt": "2026-01-15T10:30:00Z"
    },
    "prod": {
      "url": "https://tsm.example.com",
      "auth": "bearer",
      "token": "encrypted:v1:...",
      "addedAt": "2026-02-01T14:00:00Z"
    }
  },
  "default": "dev",
  "projects": {
    "acme-bss": {
      "default": "prod"
    }
  }
}

Top-level environments and default are global. The projects map allows per-project overrides (keyed by tsm-project.yaml name). Per-project entries can also contain their own environments map when projects connect to different tSM instances.

Structure

Field	Type	Description
environments	Object	Map of alias → credential entry (global).
environments.<alias>.url	String	Base URL of the tSM instance.
environments.<alias>.auth	String	Authentication type: basic or bearer.
environments.<alias>.user	String	Username (for basic auth).
environments.<alias>.password	String	Encrypted password (for basic auth).
environments.<alias>.token	String	Encrypted bearer token (for bearer auth).
environments.<alias>.addedAt	String	ISO-8601 timestamp when the credential was stored.
default	String	Global default environment alias.
projects	Object	Per-project overrides keyed by tsm-project.yaml name.
projects.<name>.default	String	Default environment alias for this project.
projects.<name>.environments	Object	Project-specific credentials (same structure as top-level environments).

Security

• Passwords and tokens are encrypted at rest using a machine-local key.
• The file is created with permission mode 600 (owner read/write only).
• The tsm auth logout command removes the entry and securely overwrites the credential.
• Credentials are never displayed in tsm auth list output — only the alias, URL, and auth type.

---

Configuration precedence

When the CLI resolves a setting, values are checked in this order (highest priority first):

Priority	Source	Example
1	Command-line flags	--target-env prod
2	Environment variables	TSM_ENV=prod
3	Per-project user config	config.json → projects.acme-bss.default-env
4	Global user config	config.json → "default-env": "dev"
5	Built-in defaults	output: table, timeout: 300

This means:

• A flag always wins.
• An environment variable overrides user config.
• Per-project user config overrides global user config.
• Global user config provides fallback values.

Environment resolution example

Given:

• tsm-project.yaml defines environments dev and prod with their URLs.
• config.json has "default-env": "dev" globally and projects.acme-bss.default-env: "prod".
• credentials.json has credentials for aliases dev and prod.
• Developer runs (without --target-env): tsm package validate AllConfig

Resolution:

1. No --target-env flag, no TSM_ENV variable.
2. Current project is acme-bss (from tsm-project.yaml).
3. config.json → projects.acme-bss.default-env = prod → priority 3.
4. URL from tsm-project.yaml environments prod → https://tsm.example.com.
5. Credentials from credentials.json for alias prod → used for authentication.

If the developer works in a different project with no per-project override, the global default-env: dev is used instead.

---

Project vs user configuration

Aspect	tsm-project.yaml	~/.tsm/config.json + credentials.json
Scope	Per workspace (shared via Git).	Per user (local to machine), with per-project overrides.
Committed to Git	Yes.	Never.
Contains credentials	No.	Yes (encrypted).
Contains env URLs	Yes (shared reference).	Yes (per-credential).
Contains packages	Yes (explicit list or autodiscovery).	No.
Contains defaults	No.	Yes (global + per-project).
Managed by	Team lead / project setup.	Individual developer / tsm config set.

Why two levels?

Project file answers: what packages exist, what environments are available? — the same for everyone.

User files answer: what are my credentials, which environment do I default to, what are my preferred CLI settings? — different per developer, optionally different per project.

This separation keeps credentials and personal preferences out of Git while still sharing environment definitions and project structure.

---

Minimal configurations

Minimal package.yaml

packageId: AllConfig
name: All Configuration
version: 0.0.1

areas:
  - id: all
    path: all
    configTypes:
      - code: Common
        includeSubtree: true

Minimal tsm-project.yaml

name: my-project

With only name, Studio auto-discovers packages by scanning the default packages/ directory.

Minimal ~/.tsm/config.json

{}

All defaults apply. The developer can still pass --target-env and --url as flags.

---

File locations summary

File	Path	Git	Purpose
Package definition	packages/<id>/package.yaml	Yes	Defines one Configuration Package.
Project settings	tsm-project.yaml	Yes	Workspace-wide project settings.
CLI preferences	~/.tsm/config.json	No	User preferences + per-project defaults.
Stored credentials	~/.tsm/credentials.json	No	Encrypted environment credentials.

---

See also

• Configuration Packages — package model, areas, and best practices
• tSM CLI — full command reference including auth and config
• Basic Workflow — package.yaml examples for a simple project
• Enterprise Workflow — package.yaml examples for multi-team projects