Version: 2.4

tSM CLI

The tSM CLI (tsm) is a command-line tool for managing tSM configuration, packages, and deployments from a terminal, CI/CD pipeline, or automation script.

The CLI follows a topic-command pattern. Each top-level topic groups related commands:

tsm <topic> <command> [flags]

The CLI supports these topics:

Topic	Purpose
`auth`	Authenticate to tSM environments.
`config`	Manage CLI user preferences (output format, timeout, color).
`package`	Create, configure, build, validate, diff, install packages.
`changeset`	Story-level change tracking.
`entity`	Read entity types and records from a target environment.

Installation

Download the latest release for your platform from the tSM Studio releases page and place it on your PATH:

# macOS / Linux
chmod +x tsm
sudo mv tsm /usr/local/bin/

# verify
tsm --version

Command overview

tsm auth login               Authenticate to a tSM environment and store credentials.
tsm auth list                 List saved environments.
tsm auth logout               Remove stored credentials for an environment.

tsm config set                Set a CLI user preference (e.g. output format, timeout).
tsm config get                Display current CLI configuration.
tsm config list               List all configuration values.

tsm package init              Scaffold a new package (creates package.yaml and area structure).
tsm package add area        Add an area definition to an existing package.yaml.
tsm package add dependency    Add a dependency to an existing package.yaml.
tsm package set version       Set or bump the version in package.yaml.
tsm package info              Display resolved package.yaml details.

tsm package download          Download environment configuration into a local package directory.
tsm package validate          Validate a package against a target environment (dry-run).
tsm package diff              Compare a package with the current environment state.
tsm package install           Install a package into a target environment.
tsm package artifact          Create a deployment artifact (full or incremental).
tsm package publish           Publish an artifact to a repository (Nexus, Harbor).

tsm package installed list    List installed packages in an environment.
tsm package installed get     Get details of a specific installed package.
tsm package installed items   List items inside an installed package.

tsm changeset create          Create a new Change Set linked to a story/task.
tsm changeset list            List Change Sets.
tsm changeset show            Display Change Set details and tracked items.
tsm changeset add             Manually add an entity to a Change Set.
tsm changeset remove          Remove an entity from a Change Set.
tsm changeset submit          Submit a Change Set for review (OPEN → IN_REVIEW).
tsm changeset close           Close a reviewed Change Set (IN_REVIEW → CLOSED).
tsm changeset abandon         Abandon an open Change Set.

tsm entity types              List all entity types available in the environment.
tsm entity list               List records of a given entity type.
tsm entity get                Get a single record by entity type and ID or code.

Authentication

`tsm auth login`

Authenticate to a tSM instance and store the credentials under an alias.

tsm auth login \
  --url https://tsm.example.com \
  --alias prod \
  --user admin \
  --password secret

The alias can then be used with --target-env on any command.

Flags

Flag	Required	Description
`--url`	Yes	Base URL of the tSM instance.
`--alias`, `-a`	Yes	Short name for this environment (e.g. `dev`, `staging`, `prod`).
`--user`, `-u`		Username for Basic authentication.
`--password`		Password for Basic authentication. Omit to be prompted interactively.
`--token`		Bearer token for OAuth / API-key flows (takes precedence over Basic).

Credentials are stored in ~/.tsm/credentials.json. The file is created with restricted permissions (600). See Configuration Reference for the full file schema.

Token-based example

tsm auth login \
  --url https://tsm.example.com \
  --alias prod \
  --token eyJhbGciOiJSUzI1NiIs...

`tsm auth list`

List all configured environments. The output combines aliases stored in ~/.tsm/credentials.json with environment aliases discovered from the nearest tsm-project.yaml.

tsm auth list

ALIAS   URL                             AUTH           DEFAULT
dev     https://dev.tsm.example.com     Basic (admin)
prod    https://tsm.example.com         Bearer         x

`tsm auth logout`

Remove stored credentials for an environment.

tsm auth logout --alias staging

Configuration

`tsm config set`

Set a CLI user preference. Preferences are stored in ~/.tsm/config.json. See Configuration Reference for the full settings reference.

tsm config set output json
tsm config set default-env test                    # global default
tsm config set default-env test --project acme-bss # per-project override

Key	Description	Values
`output`	Default output format.	`table`, `json`, `yaml`.
`timeout`	HTTP request timeout in seconds.	Integer (default: `300`).
`verbose`	Enable verbose logging by default.	`true`, `false`.
`color`	Enable or disable colored output.	`true`, `false`.
`default-env`	Target environment alias.	Any environment alias.

Use --project <name> to store a setting under the per-project section instead of the global default. Without --project, the value is written to the top-level (global) config.

`tsm config get`

Display one or all configuration values.

tsm config get output         # → json
tsm config list               # show all

Global flags

These flags are available on every command and override configuration defaults:

Flag	Env variable	Description
`--target-env`, `-e`	`TSM_ENV`	Environment alias to use (overrides user `default-env`).
`--url`	`TSM_URL`	Base URL (overrides the alias URL).
`--user`	`TSM_USER`	Username for Basic auth (overrides stored credentials).
`--password`	`TSM_PASSWORD`	Password for Basic auth.
`--token`	`TSM_TOKEN`	Bearer token (overrides stored credentials).
`--output`, `-o`	—	Output format: `table` (default), `json`, or `yaml`.
`--verbose`	—	Enable verbose / debug logging.
`--json`	—	Shorthand for `--output json`.
`--timeout`	—	HTTP request timeout in seconds (default: `300`).

Resolution order for target environment: explicit --target-env flag → TSM_ENV → per-project default-env → global default-env (both from ~/.tsm/config.json).

Environment variables override stored credentials; explicit flags override everything.

Package authoring commands

These commands work locally on package.yaml files. They do not call the server.

`tsm package init`

Scaffold a new package inside the current workspace.

Creates:

the package directory
a package.yaml with the provided values
one initial area

tsm package init \
  --package-id AllConfig \
  --name "All Configuration" \
  --version 0.0.1 \
  --path packages/AllConfig

Flags

Flag	Required	Description
`--package-id`	Yes	Stable unique package identifier. Also used as the default directory name.
`--name`	Yes	Human-readable package name.
`--version`		Initial version (default: `0.0.1`).
`--description`		Package description.
`--owner-team`		Owner team of the package.
`--path`		Directory path (default: `packages/<packageId>`).
`--area-id`		ID of the first area to create (prompted interactively if omitted).
`--area-path`		Path of the first area (default: same as `--area-id`).
`--config-type`		ConfigType code for the first area.
`--include-subtree`		Include ConfigType subtree in the first area (default: `true`).

Example

tsm package init \
  --package-id ordering-sdwan \
  --name "Ordering / SD-WAN" \
  --version 1.0.0 \
  --owner-team SDWAN \
  --path packages/ordering-sdwan \
  --area-id sdwan-product \
  --config-type cap.ordering.sdwan.product \
  --include-subtree

This creates:

packages/ordering-sdwan/
  package.yaml
  sdwan-product/

With package.yaml:

packageId: ordering-sdwan
name: Ordering / SD-WAN
version: 1.0.0
ownerTeam: SDWAN

areas:
  - id: sdwan-product
    path: sdwan-product
    configTypes:
      - code: cap.ordering.sdwan.product
        includeSubtree: true

policy:
  managed: true
  allowDelete: false
  enforceDependencies: true

`tsm package add area`

Add a new area definition to an existing package.yaml.

tsm package add area \
  --package-yaml packages/ordering-sdwan/package.yaml \
  --area-id sdwan-fulfillment \
  --description "SD-WAN-specific process and orchestration configuration." \
  --config-type cap.ordering.sdwan.fulfillment \
  --include-subtree

Flags

Flag	Required	Description
`--package-yaml`	Yes	Path to the `package.yaml` to modify.
`--area-id`	Yes	Stable area identifier.
`--area-path`		Relative area path (default: same as `--area-id`).
`--name`		Human-readable area name.
`--description`		Area description.
`--config-type`	Yes	ConfigType code to add. Repeatable for multiple ConfigTypes.
`--include-subtree`		Include ConfigType subtree (default: `true`).

The area directory is also created on disk if it does not exist.

`tsm package add dependency`

Add a dependency to an existing package.yaml.

tsm package add dependency \
  --package-yaml packages/ordering-sdwan/package.yaml \
  --dependency-id core-common \
  --version-range ">=1.0.0 <2.0.0" \
  --kind required

Flags

Flag	Required	Description
`--package-yaml`	Yes	Path to the `package.yaml` to modify.
`--dependency-id`	Yes	Package ID of the required dependency.
`--version-range`	Yes	Allowed version range (e.g. `>=1.0.0 <2.0.0`).
`--kind`		Dependency kind: `required` (default) or `optional`.

`tsm package set version`

Set or bump the version in package.yaml.

# Set an explicit version
tsm package set version \
  --package-yaml packages/AllConfig/package.yaml \
  --version 1.2.0

# Bump using semver increment
tsm package set version \
  --package-yaml packages/AllConfig/package.yaml \
  --bump minor

Flags

Flag	Required	Description
`--package-yaml`	Yes	Path to the `package.yaml` to modify.
`--version`		Explicit version string to set (e.g. `1.2.0`).
`--bump`		Semver component to increment: `major`, `minor`, or `patch`.

Either --version or --bump must be provided.

`tsm package info`

Display the resolved contents of a package.yaml.

tsm package info --package-yaml packages/AllConfig/package.yaml

Package:       AllConfig
Name:          All Configuration
Version:       1.2.0
Owner:         SolutionTeam
Description:   Main package containing all business and project-specific configuration.

DEPENDENCIES
PACKAGE        VERSION RANGE          KIND
System         >=0.0.2 <1.0.0        required

AREAS
ID             PATH           CONFIG TYPES                              SUBTREE
common         common         Common                                    yes
crm            crm            CRM                                       yes
catalog        catalog        Catalog                                   yes
ordering       ordering       Ordering                                  yes
ticketing      ticketing      Ticketing                                 yes
other          other          Other                                     yes

POLICY
managed: true    allowDelete: false    enforceDependencies: true

Package server commands

These commands call the tSM public API. They require authentication to a target environment.

By default, server commands work with a local package directory — the directory containing package.yaml and its downloaded content. The directory path is passed as a positional argument. A pre-built ZIP archive or artifact can be used instead by passing the --file flag.

`tsm package download`

Download the current environment configuration into a local package directory.

The command reads package.yaml from the given directory, sends it to the server, and downloads the matching configuration items organized by area and entity type. The downloaded content is extracted directly into the package directory.

tsm package download AllConfig

Flags

Flag	Required	Description
(positional)	Yes	Path to the local package directory containing `package.yaml`.
`--out`		Write output as a ZIP archive instead of extracting into the package directory.
`--area-code`		Limit download to a single area within the package.
`--from-timestamp`		Download only items modified after this ISO-8601 timestamp (e.g. `2025-06-01T00:00:00Z`).
`--entity-types`		Comma-separated list of entity types to include (e.g. `Form,Process,Script`). If omitted, all types are used.
`--changeset`		Download only items tracked by the given Change Set code (e.g. `US-1234`).
`--who-edited`		Comma-separated list of user IDs — download only items last edited by these users.
`--my-changes`		Shorthand for `--who-edited <current-user>`. Requires token authentication so the CLI can resolve the user ID.

Examples

Download a full package into the local directory:

tsm package download AllConfig

Download as a ZIP archive instead:

tsm package download AllConfig --out AllConfig-1.0.0.zip

Download only changes since a timestamp:

tsm package download AllConfig \
  --from-timestamp 2025-11-01T00:00:00Z

Download only specific entity types from one area:

tsm package download SDWAN \
  --area-code sdwan-product \
  --entity-types EntityCatalogSpecification,Characteristic

Download only items tracked by a Change Set:

tsm package download SDWAN --changeset US-1234

Download only items changed by the currently logged-in user (requires token auth):

tsm package download SDWAN --my-changes

Download only items last edited by specific users:

tsm package download SDWAN --who-edited bob,alice

`tsm package validate`

Validate a package with dry-run semantics. No changes are made to the target environment.

The CLI packages the local directory into an archive, sends it to the server, which parses it, resolves dependencies, and reports any structural or compatibility issues.

tsm package validate AllConfig

Flags

Flag	Required	Description
(positional)		Path to the local package directory containing `package.yaml` and content. Required unless `--file` is used.
`--file`		Use a pre-built ZIP archive instead of the local package directory.
`--area-code`		Validate only a specific area within the package.
`--entity-types`		Comma-separated list of entity types to validate (e.g. `Form,Process`). If omitted, all types are validated.

Example output

Validation result: PASSED
Package:    AllConfig 1.0.0
Items:      142
Warnings:   0
Errors:     0

Validation result: FAILED
Package:    AllConfig 1.0.0
Items:      142
Warnings:   1
Errors:     2

ERRORS:
  [1] Dependency not satisfied: System >=0.0.2 <1.0.0 (installed: none)
  [2] Missing entity reference: Form/OrderEntry references Characteristic/BandwidthTier (not found)

WARNINGS:
  [1] Entity Register/CommonStatuses already exists with different configType

`tsm package diff`

Compare a package with the current environment state and show what would change on install.

tsm package diff AllConfig

Flags

Flag	Required	Description
(positional)		Path to the local package directory containing `package.yaml` and content. Required unless `--file` is used.
`--file`		Use a pre-built ZIP archive instead of the local package directory.
`--area-code`		Diff only a specific area.
`--entity-types`		Comma-separated list of entity types to diff. If omitted, all types are compared.
`--show-details`		Show field-level diff details for modified entities.
`--diff`		Show unified content diff for changed values (raw before/after comparison).

Example output

Diff: AllConfig 1.0.0 vs current environment

ADDED (3):
  Form/SDWAN_SiteSetup
  Characteristic/SiteRole
  Process/SDWAN_OrderProvisioning

MODIFIED (2):
  Form/OrderEntry            [fields changed]
  Register/CommonStatuses    [values changed]

REMOVED (0):

UNCHANGED (137)

`tsm package install`

Install a package into the target environment and create an InstalledPackage record.

This is the primary deployment command. It validates the package, applies the configuration, and records the deployment history.

tsm package install AllConfig

Flags

Flag	Required	Description
(positional)		Path to the local package directory containing `package.yaml` and content. Required unless `--file` is used.
`--file`		Use a pre-built ZIP archive instead of the local package directory.
`--area-code`		Install only a specific area.
`--entity-types`		Comma-separated list of entity types to install. If omitted, all types are installed.
`--install-source`		Installation source label (default: `CLI`).
`--notes`		Free-text notes attached to the InstalledPackage record (e.g. ticket number or release description).
`--dry-run`		If set, equivalent to `validate`. No changes are applied.

Examples

Install with notes:

tsm package install AllConfig \
  --notes "Release 1.0.0 — initial PROD deployment, ticket PROJ-1234"

Install only specific entity types:

tsm package install AllConfig \
  --entity-types Form,Process \
  --notes "Hotfix: form and process corrections"

Install from a pre-built ZIP archive:

tsm package install --file AllConfig-1.0.0.zip \
  --notes "Release 1.0.0"

Example output

Install result: SUCCESS
Package:         AllConfig 1.0.0
Installed items: 142
Install source:  CLI
Notes:           Release 1.0.0 — initial PROD deployment, ticket PROJ-1234
Installed ID:    a3f8c2e1-7b4d-4e9a-b6c1-2d5f8a9e0b3c

`tsm package artifact`

Create a Deployment Artifact — a self-contained ZIP archive ready for review, publishing, and installation.

The command supports two modes:

Mode	What it contains	Install behavior	When to use
Full (default)	All configuration items matching `package.yaml`.	The target environment is updated to fully conform to the state of the Configuration Package. Items added, modified, or (when `allowDelete: true`) removed — the environment converges to the package.	Baseline deployments, full releases, environment resets.
Incremental	Only the items selected by a scoping flag. Everything else in the target environment is left untouched.	Only the included items are applied; no other configuration is changed.	Story-level releases, feature branches, targeted fixes.

A full artifact is the default. Add any of the scoping flags below to produce an incremental artifact instead.

Incremental scoping methods

Method	Flag	What is included
Diff to target	`--diff`	Items that differ between the local package directory and the target environment.
Git diff	`--branch-diff <range>`	Items whose files changed between two Git refs (e.g. `main...feature/X`).
File list	`--files <path>`	Items listed explicitly in a text file (one path per line).

Scoping methods can be further narrowed with --area-code and --entity-types.

# Full artifact — entire package
tsm package artifact AllConfig --target-env prod

# Incremental — only items that differ from the target
tsm package artifact AllConfig --target-env prod --diff

# Incremental — only items changed on a feature branch
tsm package artifact AllConfig \
  --branch-diff main...feature/ordering-improvements \
  --target-env test

# Incremental — only items from an explicit file list
tsm package artifact AllConfig --target-env prod \
  --files release-items.txt

Artifacts are written to the build/ directory by default.

Flags

Flag	Required	Description
(positional)	Yes	Path to the local package directory containing `package.yaml` and content.
`--target-env`	Yes	Target environment (used for diff computation and artifact naming).
`--out`		Output path for the artifact (default: `build/<packageId>-<version>-<env>.zip`).
`--diff`		Incremental mode: include only items that differ from the target environment.
`--branch-diff`		Incremental mode: include only items changed between Git refs (e.g. `main...feature/X`).
`--files`		Incremental mode: include only items listed in the given text file (one path per line).
`--area-code`		Further narrow the artifact to a specific area.
`--entity-types`		Comma-separated list of entity types to include.
`--branch-diff`		Compute diff from Git branch range instead of full content (e.g. `origin/main..HEAD`).
`--git-fetch`		Fetch remote refs before comparing (default: `true`). Set to `false` for offline use.
`--repository-root`		Path to the Git repository root. Auto-detected from the package directory if omitted.

Examples

Full artifact — baseline deployment to production:

tsm package artifact AllConfig --target-env prod

Artifact: build/AllConfig-1.1.0-prod.zip  (full)

Total: 142 items

When installed, the target environment will be updated to match the complete Configuration Package. Added items are created, modified items are updated, and — if the package policy allows it — items that no longer belong to the package are removed.

Incremental artifact — diff to target:

tsm package artifact AllConfig --target-env prod --diff

Artifact: build/AllConfig-1.1.0-prod.zip  (incremental, diff-to-target)

ADDED (1):
  Form/SDWAN_SiteSetup

MODIFIED (2):
  Form/OrderEntry            [fields changed]
  Process/OrderProvisioning  [steps changed]

Total: 3 items (139 unchanged, not included)

Only the 3 changed items will be installed. Everything else in the target environment stays as-is.

Incremental artifact — Git branch diff:

tsm package artifact AllConfig \
  --branch-diff main...feature/ordering-improvements \
  --target-env test

The CLI determines which configuration files changed between the two Git refs and includes only those items.

Incremental artifact — explicit file list:

tsm package artifact AllConfig --target-env prod \
  --files release-items.txt

Where release-items.txt contains paths relative to the package directory:

sdwan-product/Form/SDWAN_SiteSetup.json
sdwan-product/Process/OrderProvisioning.json

Narrowing with area or entity type (works with both full and incremental):

tsm package artifact AllConfig --target-env prod \
  --entity-types Form,Process

`tsm package publish`

Publish a deployment artifact to a remote repository (Nexus, Harbor, or another configured registry).

tsm package publish build/AllConfig-1.1.0-prod.zip \
  --repository nexus

Flags

Flag	Required	Description
(positional)	Yes	Path to the artifact ZIP file.
`--repository`	Yes	Target repository alias (configured in `tsm-project.yaml` or CLI config).
`--notes`		Release notes attached to the published artifact.

Example

tsm package publish build/AllConfig-1.1.0-prod.zip \
  --repository nexus \
  --notes "AllConfig 1.1.0 — ordering form improvements, PROJ-456"

`tsm package installed list`

List installed packages in the target environment.

tsm package installed list

Flags

Flag	Required	Description
`--page`		Page number for paginated results (default: `0`).
`--size`		Page size (default: `20`).
`--sort`		Sort field and direction (e.g. `installedAt,desc`).
`--filter`		Filter expression (e.g. `packageId==AllConfig`). Repeatable.

Example output

INSTALLED PACKAGES
ID                                     PACKAGE         VERSION   INSTALLED AT             SOURCE
a3f8c2e1-7b4d-4e9a-b6c1-2d5f8a9e0b3c  AllConfig       1.0.0     2025-12-01T10:30:00Z     CLI
b7e2d4f6-9a1c-4b8e-a3d5-6f0e2c7b1a4d  System          0.0.2     2025-11-28T14:15:00Z     CLI
c1a9b3e5-2d4f-4c8a-b6e0-7f3d5a1c9b2e  System          0.0.1     2025-11-15T09:00:00Z     API

`tsm package installed get`

Get details of a specific installed package by ID.

tsm package installed get a3f8c2e1-7b4d-4e9a-b6c1-2d5f8a9e0b3c

Flags

Flag	Required	Description
(positional)	Yes	InstalledPackage UUID.

Example output (JSON)

tsm package installed get a3f8c2e1-7b4d-4e9a-b6c1-2d5f8a9e0b3c --json

{
  "id": "a3f8c2e1-7b4d-4e9a-b6c1-2d5f8a9e0b3c",
  "packageId": "AllConfig",
  "name": "All Configuration",
  "version": "1.0.0",
  "description": "Main package containing all business and project-specific configuration.",
  "installedAt": "2025-12-01T10:30:00Z",
  "installSource": "CLI",
  "notes": "Release 1.0.0 — initial PROD deployment, ticket PROJ-1234",
  "itemCount": 142
}

`tsm package installed items`

List items in an installed package. By default only changed items (added, modified, removed) are shown — items whose current state in the environment matches the package are hidden. Use --all to include all items.

tsm package installed items a3f8c2e1-7b4d-4e9a-b6c1-2d5f8a9e0b3c

Flags

Flag	Required	Description
(positional)	Yes	InstalledPackage UUID.
`--page`		Page number (default: `0`).
`--size`		Page size (default: `50`).
`--filter`		Filter expression (e.g. `entityType==Form`). Repeatable.
`--all`		Include unchanged items (default: only changed items are shown).

Example output

Installed package items: a3f8c2e1-7b4d-4e9a-b6c1-2d5f8a9e0b3c
Showing: changed items only
Items on page: 3 of 142
Total items: 142

Entity Type   Code                     Name                      Config Type      Status    Source Modified       Current Modified      Changes
Form          SDWAN_SiteSetup          SD-WAN Site Setup         SDWAN.Ordering   ADDED     2026-03-01T10:00:00Z  -
Characteristic SiteRole               Site Role                 SDWAN.Ordering   ADDED     2026-03-01T10:00:00Z  -
Register      SDWANStatuses            SDWAN Statuses            SDWAN            MODIFIED  2026-03-01T10:00:00Z  2026-02-15T08:00:00Z  values changed

CI/CD integration

The CLI is designed for scripted and automated use. There are two approaches:

Direct install — commands work directly with the package directory. Simple, but the diff is computed at install time.
Artifact-based — create a deployment artifact first (tsm package artifact), then publish and install it. Recommended for production pipelines because the diff is pre-computed and reviewable.

For artifact-based CI/CD examples, see Deployment Artifacts.

The examples below show the direct-install pattern for simplicity.

GitLab CI example

stages:
  - validate
  - deploy

variables:
  TSM_URL: https://tsm.example.com
  # TSM_USER and TSM_PASSWORD set as CI/CD masked variables

validate-package:
  stage: validate
  script:
    - tsm package validate AllConfig

deploy-prod:
  stage: deploy
  needs: [validate-package]
  when: manual
  environment:
    name: production
  script:
    - tsm package diff AllConfig
    - tsm package install AllConfig --notes "CI pipeline $CI_PIPELINE_ID — $CI_COMMIT_SHORT_SHA"

GitHub Actions example

name: Deploy package
on:
  push:
    tags:
      - 'v*'

env:
  TSM_URL: ${{ secrets.TSM_URL }}
  TSM_TOKEN: ${{ secrets.TSM_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate
        run: tsm package validate AllConfig

      - name: Diff
        run: tsm package diff AllConfig

      - name: Install
        run: |
          tsm package install AllConfig \
            --notes "GitHub Actions — ${{ github.ref_name }} — ${{ github.sha }}"

Shell script example

#!/usr/bin/env bash
set -euo pipefail

PACKAGE_DIR="AllConfig"

echo "==> Validating..."
tsm package validate "$PACKAGE_DIR"

echo "==> Diff against target..."
tsm package diff "$PACKAGE_DIR"

read -rp "Proceed with installation? [y/N] " confirm
if [[ "$confirm" =~ ^[Yy]$ ]]; then
  tsm package install "$PACKAGE_DIR" --notes "Manual release $(date +%Y-%m-%d)"
  echo "==> Installed successfully."
else
  echo "==> Aborted."
fi

Typical workflow

A typical CLI workflow combines local authoring with server-side deployment:

1. Create the package

tsm package init \
  --package-id AllConfig \
  --name "All Configuration" \
  --version 0.0.1 \
  --path packages/AllConfig \
  --area-id common --config-type Common --include-subtree

tsm package add area \
  --package-yaml packages/AllConfig/package.yaml \
  --area-id ordering --config-type Ordering --include-subtree

tsm package add dependency \
  --package-yaml packages/AllConfig/package.yaml \
  --dependency-id System --version-range ">=0.0.1 <1.0.0" --kind required

2. Download content from source environment

tsm auth login --url https://dev.tsm.example.com --alias dev
tsm package download AllConfig

3. Bump version

tsm package set version \
  --package-yaml packages/AllConfig/package.yaml \
  --bump minor

4. Validate against target environment

tsm auth login --url https://prod.tsm.example.com --alias prod
tsm package validate --target-env prod AllConfig

5. Review differences

tsm package diff --target-env prod AllConfig

6. Install

tsm package install --target-env prod AllConfig --notes "Release 0.1.0"

7. Verify

tsm package installed list --target-env prod --filter "packageId==AllConfig"

Exit codes

Code	Meaning
0	Success.
1	General error (network, auth, unexpected).
2	Validation failed (errors found).
3	Dependency not satisfied.
10	Bad usage (missing flags, bad arguments).

Scripts can use exit codes to control pipeline flow:

tsm package validate AllConfig
if [ $? -eq 2 ]; then
  echo "Package has validation errors, aborting."
  exit 1
fi

Change Set commands

These commands manage Change Sets — story-level tracking units that sit on top of Configuration Packages. Change Sets track which entities were changed for a story, provide a scope for review, and maintain an audit trail.

For the full concept, see Change Sets.

`tsm changeset create`

Create a new Change Set linked to a user story or task.

tsm changeset create \
  --code US-1234 \
  --name "SD-WAN site setup form and provisioning" \
  --branch feature/US-1234

Flags

Flag	Required	Description
`--code`	Yes	Short identifier, typically matching the ticket (e.g. `US-1234`).
`--name`	Yes	Human-readable description.
`--branch`		Git branch this Change Set belongs to.
`--user-group`		Owner user group.

`tsm changeset list`

List Change Sets in the target environment.

tsm changeset list

Flags

Flag	Required	Description
`--status`		Filter by status: `OPEN`, `IN_REVIEW`, `CLOSED`.
`--owner`		Filter by owner user.

Example output

CHANGE SETS
CODE       NAME                                            STATUS      OWNER   ITEMS
US-1234    SD-WAN site setup form and provisioning          OPEN        bob     4
US-5678    Revise common statuses and shared validation     IN_REVIEW   alice   3
US-4444    Catalog restructuring                            CLOSED      carol   7

`tsm changeset show`

Display the contents and status of a Change Set.

tsm changeset show US-1234

Example output

Change Set: US-1234
Name:        SD-WAN site setup form and provisioning
Status:      OPEN
Owner:       bob
Branch:      feature/US-1234

ITEMS (4):
  CHANGE     ENTITY TYPE      CODE                        CONFIG TYPE          BASE VERSION
  ADDED      Form             SDWAN_SiteSetup             SDWAN.Ordering       —
  ADDED      Characteristic   SiteRole                    SDWAN.Ordering       —
  ADDED      Process          SDWAN_OrderProvisioning     SDWAN.Provisioning   —
  MODIFIED   Register         SDWANStatuses               SDWAN                2026-03-01T10:00:00Z

`tsm changeset add`

Manually add an entity to a Change Set.

tsm changeset add US-1234 \
  --entity-type Characteristic \
  --entity-code AccessBandwidth

Flags

Flag	Required	Description
(positional)	Yes	Change Set code.
`--entity-type`	Yes	Entity type.
`--entity-code`	Yes	Entity code.

`tsm changeset remove`

Remove an entity from a Change Set.

tsm changeset remove US-1234 \
  --entity-type Register \
  --entity-code SDWANStatuses

Flags

Flag	Required	Description
(positional)	Yes	Change Set code.
`--entity-type`	Yes	Entity type.
`--entity-code`	Yes	Entity code.

`tsm changeset submit`

Submit a Change Set for review. After submission, no further entity additions are allowed.

tsm changeset submit US-1234

The Change Set moves from OPEN to IN_REVIEW.

`tsm changeset close`

Close a reviewed Change Set. This archives the Change Set for audit purposes.

tsm changeset close US-1234

The Change Set moves from IN_REVIEW to CLOSED.

`tsm changeset abandon`

Abandon an open Change Set. Tracked entities are released.

tsm changeset abandon US-9999

A Change Set can be abandoned from OPEN or IN_REVIEW state.

For the full Change Set lifecycle, see Change Sets.

Entity commands

These commands read entity metadata and records from the target environment. They require authentication.

`tsm entity types`

List all entity types available in the environment.

tsm entity types

Output includes: entity type ID, code, name, and microservice. Use --json or --output yaml for structured output.

`tsm entity list`

List records of a given entity type.

tsm entity list BillingCycleType --page-size 50

Flags

Flag	Required	Description
(positional)	Yes	Entity type code.
`--page-size`		Number of records per page. Must be a positive integer.

Table output extracts common fields (id, code, name, description). JSON and YAML output return the raw API payload.

`tsm entity get`

Get a single record by entity type and ID or code.

tsm entity get BillingCycleType MONTHLY

The second positional argument accepts either an entity ID or a code.

API mapping

Each server-side CLI command maps to a public API endpoint:

Command	HTTP Method	Endpoint
`tsm package download`	POST	`/api/v2/installable-packages/content`
`tsm package validate`	POST	`/api/v2/installable-packages/validate`
`tsm package diff`	POST	`/api/v2/installable-packages/diff`
`tsm package install`	POST	`/api/v2/installable-packages/install`
`tsm package artifact`	—	Local + POST `/api/v2/installable-packages/diff`
`tsm package publish`	PUT	Repository-specific (Nexus/Harbor API).
`tsm package installed list`	GET	`/api/v2/installed-packages`
`tsm package installed get`	GET	`/api/v2/installed-packages/{id}`
`tsm package installed items`	GET	`/api/v2/installed-packages/{id}/items`

Local commands (init, add area, add dependency, set version, info) operate only on package.yaml files and do not call the API.

For commands that accept a local package directory, the CLI internally packages the directory into a ZIP archive before sending it to the API. The download command downloads the ZIP archive from the API and extracts it into the local package directory.

Summary

The tSM CLI provides a complete command-line workflow for Configuration Packages and Change Sets:

Authoring (local):

tsm package init — scaffold a new package
tsm package add area — add an area definition
tsm package add dependency — add a dependency
tsm package set version — set or bump version
tsm package info — display package details

Deployment (server):

tsm package download — download environment configuration into a local package directory
tsm package validate — dry-run check before installation
tsm package diff — see exactly what would change
tsm package install — deploy the package and record the installation
tsm package artifact — create a deployment artifact (full or incremental)
tsm package publish — publish an artifact to Nexus or Harbor

Change Sets (story-level tracking):

tsm changeset create — open a Change Set for a story
tsm changeset show — review tracked entities
tsm changeset submit — submit for review
tsm changeset close — close after review

Inspection (server):

tsm package installed list — list what is installed
tsm package installed get — get details of one installation
tsm package installed items — list items inside an installation

Entity reads (server):

tsm entity types — list all entity types in the environment
tsm entity list — list records of a given entity type
tsm entity get — get a single record by type and ID or code

Key benefits:

local-directory-first workflow — commands operate on the package directory by default
story-level tracking through Change Sets
local + server workflow from package creation through deployment
repeatable deployments from CI/CD pipelines
named environments with stored credentials
full audit trail through InstalledPackage records

Installation​

Command overview​

Authentication​

tsm auth login​

Flags​

Token-based example​

tsm auth list​

tsm auth logout​

Configuration​

tsm config set​

tsm config get​

Global flags​

Package authoring commands​

tsm package init​

Flags​

Example​

tsm package add area​

Flags​

tsm package add dependency​

Flags​

tsm package set version​

Flags​

tsm package info​

Package server commands​

tsm package download​

Flags​

Examples​

tsm package validate​

Flags​

Example output​

tsm package diff​

Flags​

Example output​

tsm package install​

Flags​

Examples​

Example output​

tsm package artifact​

Incremental scoping methods​

Flags​

Examples​

tsm package publish​

Flags​

Example​

tsm package installed list​

Flags​

Example output​

tsm package installed get​

Flags​

Example output (JSON)​

tsm package installed items​

Flags​

Example output​

CI/CD integration​

GitLab CI example​

GitHub Actions example​

Shell script example​

Typical workflow​

1. Create the package​

2. Download content from source environment​

3. Bump version​

4. Validate against target environment​

5. Review differences​

6. Install​

7. Verify​

Exit codes​

Change Set commands​

tsm changeset create​

Flags​

tsm changeset list​

Flags​

Example output​

tsm changeset show​

Example output​

tsm changeset add​

Flags​

tsm changeset remove​

Flags​

tsm changeset submit​

tsm changeset close​

Installation

Command overview

Authentication

`tsm auth login`

Flags

Token-based example

`tsm auth list`

`tsm auth logout`

Configuration

`tsm config set`

`tsm config get`

Global flags

Package authoring commands

`tsm package init`

Flags

Example

`tsm package add area`

Flags

`tsm package add dependency`

Flags

`tsm package set version`

Flags

`tsm package info`

Package server commands

`tsm package download`

Flags

Examples

`tsm package validate`

Flags

Example output

`tsm package diff`

Flags

Example output

`tsm package install`

Flags

Examples

Example output

`tsm package artifact`

Incremental scoping methods

Flags

Examples

`tsm package publish`

Flags

Example

`tsm package installed list`

Flags

Example output

`tsm package installed get`

Flags

Example output (JSON)

`tsm package installed items`

Flags

Example output

CI/CD integration

GitLab CI example

GitHub Actions example

Shell script example

Typical workflow

1. Create the package

2. Download content from source environment

3. Bump version

4. Validate against target environment

5. Review differences

6. Install

7. Verify

Exit codes

Change Set commands

`tsm changeset create`

Flags

`tsm changeset list`

Flags

Example output

`tsm changeset show`

Example output

`tsm changeset add`

Flags

`tsm changeset remove`

Flags

`tsm changeset submit`

`tsm changeset close`