Work with configuration packages

Goal: author locally, then deliberately validate/diff/install into a chosen target. Complete Workspaces first and keep WORKSPACE set to its absolute path. Set PACKAGE to a new directory under that workspace. Creating and inspecting a package needs no server:

export PACKAGE="$WORKSPACE/packages/demo-config"

tsm package init --path "${PACKAGE}" --package-id demo-config --name 'Demo configuration' --area-id shared --config-type Form
tsm package info --package-yaml "${PACKAGE}/package.yaml"

Expected: package.yaml plus a shared area directory; info shows demo-config and its version. Populate configuration items using ConfigTypes supported by your deployment. Creating an empty package does not prove deployment compatibility. After connecting, review remote changes explicitly:

tsm --context dev package validate "$PACKAGE"
tsm --context dev package diff "$PACKAGE"
tsm --context dev package install "$PACKAGE"

Validate/diff are read-only server checks. Install writes configuration; use a disposable tenant for a first trial. Use the command builder for artifact create/publish, Change Sets and installed-package lifecycle flags. Cleanup: retain the local package in Git; uninstall is a separate server mutation, not file deletion.

Build a transport artifact

After filling and validating the package, create a ZIP for a selected target:

tsm --context dev package artifact create "$PACKAGE" --out build/demo-config.zip
tsm --context dev package validate --file build/demo-config.zip
tsm --context dev package diff --file build/demo-config.zip

These server-backed commands are manual integration steps. Artifact create reads the selected environment; it does not install the result. Review diff before an explicit install. Never infer a trusted target from the ZIP filename.

The install exit code also checks the server installation status and item errors. A failed install does not start a DataModel refresh; supplementary item-count lookups cannot hide the installation result. JSON/YAML retain that result.

Directory and ZIP inputs use the same import path:

tsm package install packages/demo-config
tsm package install build/demo-config.zip
tsm package install --file build/demo-config.zip
tsm app data import packages/demo-data
tsm app data import --file build/demo-data.zip
tsm app mock install packages/demo-mocks
tsm app mock install build/demo-mocks.zip

Data import retains its conflict policy (--overwrite-existing is explicit). Mock install updates an already allocated tenant binding at the observed optimistic revision; use tenant creation with --mock-package to reserve a fresh runtime. See uploaded tenant inputs.

Git artifact operations run without interactive Git prompts or stdin. --git-timeout SECONDS sets the fetch/checkout limit (default 300); other Git operations also have bounded timeouts. Temporary worktrees are cleaned after completion, errors and interrupts.