@transcend-io/cli 10.15.0 → 10.17.0

package/README.md

@@ -55,6 +55,7 @@ A command line interface that allows you to programatically interact with the Tr
   - [`transcend admin parquet-to-csv`](#transcend-admin-parquet-to-csv)
   - [`transcend migration sync-ot`](#transcend-migration-sync-ot)
   - [`transcend policy activate`](#transcend-policy-activate)
+  - [`transcend policy deactivate`](#transcend-policy-deactivate)
   - [`transcend policy eval`](#transcend-policy-eval)
   - [`transcend policy lint`](#transcend-policy-lint)
   - [`transcend policy list`](#transcend-policy-list)
@@ -2430,7 +2431,7 @@ transcend consent delete-preference-records \
 
 ```txt
 USAGE
-  transcend inventory pull (--auth value) [--resources all|apiKeys|customFields|templates|dataSilos|enrichers|dataFlows|businessEntities|processingActivities|actions|dataSubjects|identifiers|cookies|consentManager|partitions|prompts|promptPartials|promptGroups|agents|agentFunctions|agentFiles|vendors|dataCategories|processingPurposes|actionItems|actionItemCollections|teams|privacyCenters|policies|messages|assessments|assessmentTemplates|purposes|systemDiscovery] [--file value] [--transcendUrl value] [--dataSiloIds value]... [--integrationNames value]... [--trackerStatuses LIVE|NEEDS_REVIEW] [--pageSize value] [--skipDatapoints] [--skipSubDatapoints] [--includeGuessedCategories] [--debug]
+  transcend inventory pull (--auth value) [--resources all|apiKeys|customFields|templates|dataSilos|enrichers|dataFlows|businessEntities|processingActivities|actions|dataSubjects|identifiers|cookies|consentManager|partitions|prompts|promptPartials|promptGroups|agents|agentFunctions|agentFiles|vendors|dataCategories|processingPurposes|actionItems|actionItemCollections|teams|privacyCenters|policies|messages|assessments|assessmentTemplates|purposes|preferenceOptions|systemDiscovery] [--file value] [--transcendUrl value] [--dataSiloIds value]... [--integrationNames value]... [--trackerStatuses LIVE|NEEDS_REVIEW] [--pageSize value] [--skipDatapoints] [--skipSubDatapoints] [--includeGuessedCategories] [--debug]
   transcend inventory pull --help
 
 Generates a transcend.yml by pulling the configuration from your Transcend instance.
@@ -2444,7 +2445,7 @@ This command can be helpful if you are looking to:
 
 FLAGS
       --auth                       The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. The scopes required will vary depending on the operation performed. If in doubt, the Full Admin scope will always work.
-     [--resources]                 The different resource types to pull in. Defaults to dataSilos,enrichers,templates,apiKeys.                                                                                                                                                                 [all|apiKeys|customFields|templates|dataSilos|enrichers|dataFlows|businessEntities|processingActivities|actions|dataSubjects|identifiers|cookies|consentManager|partitions|prompts|promptPartials|promptGroups|agents|agentFunctions|agentFiles|vendors|dataCategories|processingPurposes|actionItems|actionItemCollections|teams|privacyCenters|policies|messages|assessments|assessmentTemplates|purposes|systemDiscovery, separator = ,]
+     [--resources]                 The different resource types to pull in. Defaults to dataSilos,enrichers,templates,apiKeys.                                                                                                                                                                 [all|apiKeys|customFields|templates|dataSilos|enrichers|dataFlows|businessEntities|processingActivities|actions|dataSubjects|identifiers|cookies|consentManager|partitions|prompts|promptPartials|promptGroups|agents|agentFunctions|agentFiles|vendors|dataCategories|processingPurposes|actionItems|actionItemCollections|teams|privacyCenters|policies|messages|assessments|assessmentTemplates|purposes|preferenceOptions|systemDiscovery, separator = ,]
      [--file]                      Path to the YAML file to pull into                                                                                                                                                                                                                          [default = ./transcend.yml]
      [--transcendUrl]              URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported.                                                          [default = https://api.transcend.io]
      [--dataSiloIds]...            The UUIDs of the data silos that should be pulled into the YAML file                                                                                                                                                                                        [separator = ,]
@@ -2496,6 +2497,7 @@ The API key permissions for this command vary based on the `resources` argument:
 | `assessments`           | `assessments`             | Assessment responses.                                                                                                                                            | View Assessments                                     | [Assessments -> Assessments](https://app.transcend.io/assessments/groups)                                                                                                                                                                              |
 | `assessmentTemplates`   | `assessment-templates`    | Assessment template configurations.                                                                                                                              | View Assessments                                     | [Assessment -> Templates](https://app.transcend.io/assessments/form-templates)                                                                                                                                                                         |
 | `purposes`              | `purposes`                | Consent purposes and related preference management topics.                                                                                                       | View Consent Manager, View Preference Store Settings | [Consent Management -> Regional Experiences -> Purposes](https://app.transcend.io/consent-manager/regional-experiences/purposes)                                                                                                                       |
+| `preferenceOptions`     | `preference-options`      | Preference option values for single and multi-select preference topics (Preferences -> Preference Topics -> Options tab).                                        | View Preference Store Settings                       | [Preferences -> Preference Topics -> Options](https://app.transcend.io/preference-store/preference-topics/preference-options)                                                                                                                          |
 | `systemDiscovery`       | `system-discovery`        | System discovery results                                                                                                                                         | View Data Map                                        | [System Discovery](https://app.transcend.io/data-map/data-inventory/silo-discovery)                                                                                                                                                                    |
 
 #### Examples
@@ -2708,6 +2710,7 @@ The API key permissions for this command vary based on the resources declared as
 | `assessments`           | `assessments`             | Assessment responses.                                                                                                                                            | Manage Assessments                                       | [Assessments -> Assessments](https://app.transcend.io/assessments/groups)                                                                                                                                                                              |
 | `assessmentTemplates`   | `assessment-templates`    | Assessment template configurations.                                                                                                                              | Manage Assessments                                       | [Assessment -> Templates](https://app.transcend.io/assessments/form-templates)                                                                                                                                                                         |
 | `purposes`              | `purposes`                | Consent purposes and related preference management topics.                                                                                                       | Manage Consent Manager, Manage Preference Store Settings | [Consent Management -> Regional Experiences -> Purposes](https://app.transcend.io/consent-manager/regional-experiences/purposes)                                                                                                                       |
+| `preferenceOptions`     | `preference-options`      | Preference option values for single and multi-select preference topics (Preferences -> Preference Topics -> Options tab).                                        | Manage Preference Store Settings                         | [Preferences -> Preference Topics -> Options](https://app.transcend.io/preference-store/preference-topics/preference-options)                                                                                                                          |
 | `systemDiscovery`       | `system-discovery`        | System discovery results                                                                                                                                         | Manage Data Map                                          | [System Discovery](https://app.transcend.io/data-map/data-inventory/silo-discovery)                                                                                                                                                                    |
 
 #### Examples
@@ -2798,6 +2801,15 @@ Some things to note about this sync process:
 - a) Data silo owners: If you assign an email address to a data silo, you must first make sure that user is invited into your Transcend instance (https://app.transcend.io/admin/users).
 - b) API keys: This CLI will not create new API keys. You will need to first create the new API keys on the Admin Dashboard (https://app.transcend.io/infrastructure/api-keys). You can then list out the titles of the API keys that you generated in your transcend.yml file, after which the CLI is capable of updating that API key to be able to respond to different data silos in your Data Map
 
+#### Preference management push notes
+
+When pushing `purposes`, `preference-options`, or nested `preference-topics`:
+
+- **Slug format:** Preference topic and option value slugs must match `/^[A-Za-z]+$/` (alphabetical letters only — no digits, dashes, or underscores). The CLI validates this before any API calls. Topic slugs are normalized to PascalCase server-side, so YAML slugs should already be PascalCase or matching will break on subsequent pulls.
+- **Built-in purposes:** Default purposes (Advertising, Analytics, Essential, Functional, SaleOfInfo) can be updated via API key for most fields (`description`, `title`, `display-order`, `show-in-privacy-center`, `auth-level`, etc.). The CLI omits `configurable` and `show-in-consent-manager` from updates for built-in purposes and logs a warning if your YAML differs on those fields — change them in the [Admin Dashboard](https://app.transcend.io/consent-manager/regional-experiences/purposes) instead.
+- **BOOLEAN topics:** Do not define `options` for `BOOLEAN` preference topics — the backend auto-creates True/False options. The CLI rejects non-empty options before push.
+- **Immutable topic fields:** Slug, type, and parent purpose cannot be changed for an existing preference topic. Attempting to change `type` in YAML is rejected by the CLI.
+
 #### CI Integration
 
 Once you have a workflow for creating your transcend.yml file, you will want to integrate your `transcend inventory push` command on your CI.
@@ -3670,20 +3682,20 @@ transcend migration sync-ot --source=file --file=./oneTrustAssessments.json --tr
 
 ```txt
 USAGE
-  transcend policy activate [--version value] [--policyBundleId value] [--bundleName value] (--auth value) [--transcendUrl value] [--dryRun] [--json]
+  transcend policy activate [--version value] [--policy-bundle-id value] [--bundle-name value] (--auth value) [--transcend-url value] [--dry-run] [--json]
   transcend policy activate --help
 
 Calls the Policy Engine activate endpoint to make an uploaded version live. Requires the parent bundle UUID or bundle name. When --version is omitted, activates the latest uploaded version by createdAt. Requires a Transcend API key with Activate Policy scope.
 
 FLAGS
-     [--version]         Caller-supplied version label to activate; defaults to the latest uploaded version by createdAt
-     [--policyBundleId]  Parent policy bundle UUID
-     [--bundleName]      Parent bundle name (used when policyBundleId is omitted)
-      --auth             The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Activate Policy"
-     [--transcendUrl]    URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--dryRun]          Validate activation without flipping the active version                                                                                                                                            [default = false]
-     [--json]            Print the raw JSON API response                                                                                                                                                                    [default = false]
-  -h  --help             Print help information and exit
+     [--version]           Caller-supplied version label to activate; defaults to the latest uploaded version by createdAt
+     [--policy-bundle-id]  Parent policy bundle UUID
+     [--bundle-name]       Parent bundle name (used when --policy-bundle-id is omitted)
+      --auth               The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Activate Policy"
+     [--transcend-url]     URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
+     [--dry-run]           Validate activation without flipping the active version                                                                                                                                            [default = false]
+     [--json]              Print the raw JSON API response                                                                                                                                                                    [default = false]
+  -h  --help               Print help information and exit
 ```
 
 #### Examples
@@ -3691,13 +3703,13 @@ FLAGS
 **Activate the latest uploaded version for a bundle**
 
 ```sh
-transcend policy activate --bundleName=main --auth="$TRANSCEND_API_KEY"
+transcend policy activate --bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Activate a specific version label by bundle name**
 
 ```sh
-transcend policy activate --version=abc123 --bundleName=main --auth="$TRANSCEND_API_KEY"
+transcend policy activate --version=abc123 --bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Activate using explicit parent bundle UUID**
@@ -3705,20 +3717,59 @@ transcend policy activate --version=abc123 --bundleName=main --auth="$TRANSCEND_
 ```sh
 transcend policy activate \
   --version=abc123 \
-  --policyBundleId=6a3218db-5703-44eb-8d01-e3ea57ab8e49 \
+  --policy-bundle-id=6a3218db-5703-44eb-8d01-e3ea57ab8e49 \
   --auth="$TRANSCEND_API_KEY"
 ```
 
 **Validate activation without flipping the active version**
 
 ```sh
-transcend policy activate --version=abc123 --bundleName=main --auth="$TRANSCEND_API_KEY" --dryRun
+transcend policy activate --version=abc123 --bundle-name=main --auth="$TRANSCEND_API_KEY" --dry-run
+```
+
+**Omit --auth by exporting TRANSCEND_API_KEY in the environment**
+
+```sh
+transcend policy activate --bundle-name=main
+```
+
+Requires the **Activate Policy** scope on your API key.
+
+### `transcend policy deactivate`
+
+```txt
+USAGE
+  transcend policy deactivate (--bundle-name value) (--auth value) [--transcend-url value] [--json]
+  transcend policy deactivate --help
+
+Calls the Policy Engine deactivate endpoint to take the currently active version of a bundle offline, clearing its active version pointer. Addressed by bundle name (resolved to the parent bundle UUID internally). Requires a Transcend API key with Activate Policy scope.
+
+FLAGS
+      --bundle-name     Logical policy bundle name (the same string used in publish/list); resolved to the parent bundle UUID internally
+      --auth            The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Activate Policy"
+     [--transcend-url]  URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
+     [--json]           Print the raw JSON API response                                                                                                                                                                    [default = false]
+  -h  --help            Print help information and exit
+```
+
+#### Examples
+
+**Deactivate the active version of a bundle by name**
+
+```sh
+transcend policy deactivate --bundle-name=main --auth="$TRANSCEND_API_KEY"
+```
+
+**Print the raw JSON response**
+
+```sh
+transcend policy deactivate --bundle-name=main --auth="$TRANSCEND_API_KEY" --json
 ```
 
 **Omit --auth by exporting TRANSCEND_API_KEY in the environment**
 
 ```sh
-transcend policy activate --bundleName=main
+transcend policy deactivate --bundle-name=main
 ```
 
 Requires the **Activate Policy** scope on your API key.
@@ -3773,18 +3824,18 @@ transcend policy lint --dir=./policies
 
 ```txt
 USAGE
-  transcend policy list (--auth value) [--transcendUrl value] [--limit value] [--offset value] [--json]
+  transcend policy list (--auth value) [--transcend-url value] [--limit value] [--offset value] [--json]
   transcend policy list --help
 
 Lists policy bundles registered for the authenticated organization. Requires a Transcend API key with View Policy scope.
 
 FLAGS
-      --auth           The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
-     [--transcendUrl]  URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--limit]         Maximum number of bundles to return                                                                                                                                                                [default = 50]
-     [--offset]        Number of records to skip before returning results                                                                                                                                                 [default = 0]
-     [--json]          Print the raw JSON API response                                                                                                                                                                    [default = false]
-  -h  --help           Print help information and exit
+      --auth            The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
+     [--transcend-url]  URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
+     [--limit]          Maximum number of bundles to return                                                                                                                                                                [default = 50]
+     [--offset]         Number of records to skip before returning results                                                                                                                                                 [default = 0]
+     [--json]           Print the raw JSON API response                                                                                                                                                                    [default = false]
+  -h  --help            Print help information and exit
 ```
 
 #### Examples
@@ -3813,20 +3864,20 @@ Requires the **View Policy** scope on your API key.
 
 ```txt
 USAGE
-  transcend policy publish (--dir value) (--bundleName value) (--auth value) [--transcendUrl value] [--version value] [--description value] [--json]
+  transcend policy publish (--dir value) (--bundle-name value) (--auth value) [--transcend-url value] [--version value] [--description value] [--json]
   transcend policy publish --help
 
 Packages manifest.json and .rego policy files from a local directory into a tarball and uploads it to Transcend. Creates the bundle on first upload, then appends immutable versions. Requires the `opa` CLI on PATH (for `opa check` and `opa build` validation) and a Transcend API key with Manage Policy scope.
 
 FLAGS
-      --dir            Directory containing manifest.json and Rego policy files
-      --bundleName     Tenant-unique policy bundle name
-      --auth           The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Manage Policy"
-     [--transcendUrl]  URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--version]       Version label (defaults to {bundleName}-yyyy-mm-dd-hh-mm-ss)
-     [--description]   Optional description for the uploaded version
-     [--json]          Print the raw JSON API response                                                                                                                                                                    [default = false]
-  -h  --help           Print help information and exit
+      --dir             Directory containing manifest.json and Rego policy files
+      --bundle-name     Tenant-unique policy bundle name
+      --auth            The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Manage Policy"
+     [--transcend-url]  URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
+     [--version]        Version label (defaults to {bundleName}-yyyy-mm-dd-hh-mm-ss)
+     [--description]    Optional description for the uploaded version
+     [--json]           Print the raw JSON API response                                                                                                                                                                    [default = false]
+  -h  --help            Print help information and exit
 ```
 
 #### Examples
@@ -3834,7 +3885,7 @@ FLAGS
 **Publish a local policy directory as the main bundle**
 
 ```sh
-transcend policy publish --dir=./policies --bundleName=main --auth="$TRANSCEND_API_KEY"
+transcend policy publish --dir=./policies --bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Publish with an explicit version label and description**
@@ -3842,7 +3893,7 @@ transcend policy publish --dir=./policies --bundleName=main --auth="$TRANSCEND_A
 ```sh
 transcend policy publish \
   --dir=./policies \
-  --bundleName=main \
+  --bundle-name=main \
   --auth="$TRANSCEND_API_KEY" \
   --version=2026-06-25 \
   --description="Quarterly policy update"
@@ -3853,15 +3904,15 @@ transcend policy publish \
 ```sh
 transcend policy publish \
   --dir=./policies \
-  --bundleName=common \
+  --bundle-name=common \
   --auth="$TRANSCEND_API_KEY" \
-  --transcendUrl=https://api.us.transcend.io
+  --transcend-url=https://api.us.transcend.io
 ```
 
 **Omit --auth by exporting TRANSCEND_API_KEY in the environment**
 
 ```sh
-transcend policy publish --dir=./policies --bundleName=main
+transcend policy publish --dir=./policies --bundle-name=main
 ```
 
 Requires the **Manage Policy** scope on your API key.
@@ -3892,19 +3943,19 @@ transcend policy test --dir=./policies
 
 ```txt
 USAGE
-  transcend policy versions (--bundleName value) (--auth value) [--transcendUrl value] [--limit value] [--after value] [--json]
+  transcend policy versions (--bundle-name value) (--auth value) [--transcend-url value] [--limit value] [--after value] [--json]
   transcend policy versions --help
 
 Resolves a bundle name to its UUID and lists uploaded versions. Requires a Transcend API key with View Policy scope.
 
 FLAGS
-      --bundleName     Tenant-unique policy bundle name
-      --auth           The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
-     [--transcendUrl]  URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--limit]         Maximum number of versions to return                                                                                                                                                               [default = 50]
-     [--after]         Opaque cursor from a previous response pageInfo.endCursor
-     [--json]          Print the raw JSON API response                                                                                                                                                                    [default = false]
-  -h  --help           Print help information and exit
+      --bundle-name     Tenant-unique policy bundle name
+      --auth            The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
+     [--transcend-url]  URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
+     [--limit]          Maximum number of versions to return                                                                                                                                                               [default = 50]
+     [--after]          Opaque cursor from a previous response pageInfo.endCursor
+     [--json]           Print the raw JSON API response                                                                                                                                                                    [default = false]
+  -h  --help            Print help information and exit
 ```
 
 #### Examples
@@ -3912,19 +3963,19 @@ FLAGS
 **List versions for a policy bundle**
 
 ```sh
-transcend policy versions --bundleName=main --auth="$TRANSCEND_API_KEY"
+transcend policy versions --bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Fetch the next page of versions using an after cursor**
 
 ```sh
-transcend policy versions --bundleName=main --auth="$TRANSCEND_API_KEY" --after="$POLICY_VERSION_CURSOR"
+transcend policy versions --bundle-name=main --auth="$TRANSCEND_API_KEY" --after="$POLICY_VERSION_CURSOR"
 ```
 
 **Omit --auth by exporting TRANSCEND_API_KEY in the environment**
 
 ```sh
-transcend policy versions --bundleName=main
+transcend policy versions --bundle-name=main
 ```
 
 Requires the **View Policy** scope on your API key.