diff --git a/content/features/te-cli/includes/te-cli-preview-notice.md b/content/features/te-cli/includes/te-cli-preview-notice.md index 6c4131be9..ced47085a 100644 --- a/content/features/te-cli/includes/te-cli-preview-notice.md +++ b/content/features/te-cli/includes/te-cli-preview-notice.md @@ -1,2 +1,2 @@ > [!IMPORTANT] -> The Tabular Editor CLI is in **Limited Public Preview**. It is offered for evaluation with a Tabular Editor account; no license is required during preview. Commands, flags, and outputs may change before general availability. **The preview build stops functioning after 2026-09-30.** We recommend against using the CLI in production CI/CD pipelines during preview. Please refer to our license agreement. +> The Tabular Editor CLI is in **Limited Public Preview**. It is offered for evaluation with a Tabular Editor account; no license is required during preview. Commands, flags, and outputs may change before general availability. **The preview build stops functioning after 2026-09-30.** We recommend against using the CLI in production CI/CD pipelines during preview. diff --git a/content/features/te-cli/te-cli-auth.md b/content/features/te-cli/te-cli-auth.md index d4e174116..bd92d2139 100644 --- a/content/features/te-cli/te-cli-auth.md +++ b/content/features/te-cli/te-cli-auth.md @@ -110,6 +110,9 @@ te connect ./my-model # Connect to a running Power BI Desktop instance (Windows only) te connect --local +# Filter by report name when multiple Power BI Desktop instances are running +te connect --local my-report + # Show the active connection te connect diff --git a/content/features/te-cli/te-cli-automation.md b/content/features/te-cli/te-cli-automation.md index 0b6211f88..bba3c780e 100644 --- a/content/features/te-cli/te-cli-automation.md +++ b/content/features/te-cli/te-cli-automation.md @@ -54,7 +54,7 @@ Every `te` command exits with a predictable status code so callers can branch on | Exit | Meaning | | -- | -- | | `0` | Success. | -| `1` | Generic failure - invalid arguments, command failed, validation errors, auth failure, BPA gate failed at severity ≥ error. For `te diff`: differences found (like the `diff`/`cmp` convention). | +| `1` | Generic failure - invalid arguments, command failed, validation errors, auth failure, BPA gate failed at severity >= error. For `te diff`: differences found (like the `diff`/`cmp` convention). | | `2` | `te diff` only: an error occurred while comparing, so the difference status is unknown. | Combine exit codes with `--ci ` annotations and `--trx ` to surface rich failure information in CI - see @te-cli-cicd. diff --git a/content/features/te-cli/te-cli-cicd.md b/content/features/te-cli/te-cli-cicd.md index c5676b754..0ccd379b2 100644 --- a/content/features/te-cli/te-cli-cicd.md +++ b/content/features/te-cli/te-cli-cicd.md @@ -166,7 +166,7 @@ steps: `te deploy` and `te save` run the Best Practice Analyzer as a pre-flight gate by default. Three behaviors are worth determining up-front: -- **Enforce** - the default. Pipeline fails if BPA finds violations at severity ≥ error. Pair with `--fail-on warning` on a standalone `te bpa run` step if you want warnings to fail too. +- **Enforce** - the default. Pipeline fails if BPA finds violations at severity >= error. Pair with `--fail-on warning` on a standalone `te bpa run` step if you want warnings to fail too. - **Auto-fix** - `--fix-bpa` applies `fixExpression`s in memory for the deployed artifact. Source files are not modified. Useful when the source of truth lives in the model and you want deploys to normalize style without developer intervention. - **Bypass** - `--skip-bpa` disables the gate for a single command. Useful for emergency hotfixes; not recommended as a default. diff --git a/content/features/te-cli/te-cli-commands.md b/content/features/te-cli/te-cli-commands.md index 727993013..ab8ebc905 100644 --- a/content/features/te-cli/te-cli-commands.md +++ b/content/features/te-cli/te-cli-commands.md @@ -42,9 +42,9 @@ Both path forms share the same syntax rules; they differ in only two places: A path is a slash-separated sequence of **segments**. Each segment names a single step - a table, a child object, or a container keyword. -- `Sales` — one segment -- `Sales/Revenue` — two segments -- `Roles/Admin/Members/bob` — four segments +- `Sales` - one segment +- `Sales/Revenue` - two segments +- `Roles/Admin/Members/bob` - four segments Empty input and `.` both mean "the model root" - the implicit starting point for filter paths and the explicit subject for `te get .`-style queries. @@ -124,7 +124,7 @@ These flags are available on every command and can be used before or after the s | Option | Description | | -- | -- | | `-m, --model ` | Path to semantic model (TMDL folder, `.bim` file, or TE folder). | -| `-s, --server ` | Workspace name or endpoint (e.g., `MyWorkspace`, `powerbi://...`, `asazure://...`, `localhost`). | +| `-s, --server ` | Analysis Services endpoint or Power BI workspace. A server name/FQDN (`MY.SERVER.COM`), IP address (`192.168.1.1`), `host:port`, `localhost`, `SERVER\INSTANCE`, `asazure://...`, or an MSOLAP connection string connects directly to Analysis Services / AAS. A bare single-token name (`MyWorkspace`), a Fabric `Name.Workspace[/Model.SemanticModel]` path, or a `powerbi://...` URL targets a Power BI workspace. A workspace name containing a dot is indistinguishable from a server name, so it is treated as a server and the CLI prints a warning; use its `.Workspace` form or full `powerbi://` URL to target Power BI. | | `-d, --database ` | Semantic model name on the workspace. | | `--local` | Connect to a locally running Power BI Desktop instance (Windows only). | | `--auth ` | Auth method: `auto`, `interactive`, `spn`, `env`, `managed-identity` (default: `auto`). | @@ -144,7 +144,7 @@ positional `` argument → `--model` global flag → `--server`/`--databa ### load -Load a semantic model and display a summary of the model — name, compatibility level, and high-level object counts (tables, measures, columns). +Load a semantic model and display a summary of the model - name, compatibility level, and high-level object counts (tables, measures, columns). ```bash te load ./model # TMDL folder @@ -158,8 +158,8 @@ Save a model to disk. Use it to write a remote workspace model to local files, c `te save` accepts: -- `-o, --output-path ` - target file or folder. **Optional** - when omitted, `te save` writes back to the source location, preserving the original format. -- `--serialization ` - `tmdl`, `bim`, `te-folder`, `pbip`, `database.json`. Defaults to inferring from the loaded model (BIM source → BIM, TMDL `SemanticModel/` → TMDL under `definition/`). +- `-o, --output-path ` - target file or folder. **Optional** - when omitted, `te save` writes back to the source location, preserving the original format. The file extension also drives format inference: `.bim` writes a single-file BIM, `.json` writes a `database.json` folder, and a bare path writes a TMDL folder. +- `--serialization ` - `tmdl`, `bim` (alias `tmsl`), `database.json`, `pbip`. When omitted, the format is inferred from the `-o` path extension (or from the loaded model when `-o` is omitted entirely). - `--force` - skip validation and overwrite existing output. Some refusals (ambiguous containers, multi-`SemanticModel` project roots) fire even under `--force`. - `--skip-bpa` - bypass the BPA gate entirely. - `--fix-bpa` - auto-fix BPA violations where rules define a fix expression. @@ -179,10 +179,12 @@ te save -o ./out -s my-workspace -d my-model --skip-validation # Fast download ### open -Open a model in Tabular Editor 3 Desktop. **Windows only** (requires TE3 to be installed). +Open a model in Tabular Editor 3 Desktop. **Windows only** (requires TE3 to be installed). With no arguments, launches TE3 with a blank workspace. ```bash -te open ./my-model +te open # Launch TE3 with a blank workspace +te open ./my-model # Open a TMDL folder in TE3 +te open ./model.bim # Open a BIM file in TE3 ``` ### init @@ -195,7 +197,7 @@ Create a new empty semantic model at the given path. Defaults to a TMDL model in - `--compatibility-mode ` - `PowerBI` (default) or `AnalysisServices`. - `--compatibility-level ` (alias `--compat`) - compatibility level. Defaults to `1702` when the mode is `PowerBI`, `1500` otherwise. See @update-compatibility-level. - `--name ` - model/database name (default: the directory name). -- `--serialization ` - `tmdl` (default), `bim`, `te-folder`, `pbip`. +- `--serialization ` - `tmdl` (default), `bim` (alias `tmsl`), `database.json`, `pbip`. - `--force` - replace any existing file or directory at the target path. ```bash @@ -213,14 +215,18 @@ Set a property on a model object. Accepts a ``. `te set` accepts: -- `-q ` - property name (e.g., `expression`, `formatString`, `description`, `isHidden`). -- `-i ` - value (use `-` to read from stdin). +- `-q ` - property name (e.g., `expression`, `formatString`, `description`, `isHidden`). **Repeatable** - pair each `-q` with a following `-i` to set multiple properties in one command. +- `-i ` - value (use `-` to read from stdin). One `-i` per `-q`. +- `-t, --type ` - disambiguation when the same path could resolve to multiple object kinds (`Measure`, `Column`, `CalculatedColumn`, `Hierarchy`, `Calendar`, `Partition`, `CalculationItem`). - `--save` / `--save-to ` - persist changes. +- `--serialization ` - override the serialization when saving (`tmdl`, `bim` (alias `tmsl`), `database.json`). +- `--force` - save even if the mutation introduces DAX validation errors. ```bash te set Sales/Amount -q expression -i "SUM(Sales[Amt])" --save te set "'Net Sales'[Sales Amount]" -q formatString -i "#,0" --save # DAX form with spaced names te set Sales -q isHidden -i true --save +te set Sales/Amount -q formatString -i "#,0" -q description -i "Net sales" --save # Multi-property ``` ### add @@ -230,7 +236,14 @@ Add an object to the model. Pass a `` for the new object (the parent must `te add` accepts: - `-t, --type ` - object type. Common values: `Table`, `Measure`, `Column`, `CalculatedColumn`, `Hierarchy`, `Role`, `Perspective`, `Culture`, `CalculationGroup`, `CalculationItem`. Tab-completion is supported; the full list can be retrieved by running `te add --help`. +- `-i ` - expression or value to assign to the new object (DAX for measures/calculated columns, M for partitions, etc.). Pair with `-q` to set additional properties on the new object in the same command. +- `-q ` - additional property to set on the new object (repeatable; pairs with `-i`). +- `--file ` - read the expression for `-i` from a file instead of inline. +- `--mode ` - storage mode for new tables: `import` (default), `directQuery`, `dual`, `directLake`. - `--if-not-exists` - exit `0` without error if the object already exists. Use this for idempotent CI/CD pipelines. +- `--save` / `--save-to ` - persist changes. +- `--serialization ` - override the serialization when saving (`tmdl`, `bim` (alias `tmsl`), `database.json`). +- `--force` - save even if the mutation introduces DAX validation errors. ```bash te add Sales/Revenue -t Measure -i "SUM(Sales[Amount])" --save @@ -249,11 +262,13 @@ Remove an object. Checks dependents by default to prevent breaking existing refe `te rm` accepts: -- `` — positional argument: the object to remove. -- `--force` — bypass the dependents check. -- `--if-exists` — exit `0` without error if the object doesn't exist. Use this for idempotent CI/CD pipelines. -- `--dry-run` — preview the removal without applying it. -- `--save` — persist the change to the loaded model. +- `` - positional argument: the object to remove. +- `-t, --type ` - disambiguate when the path matches multiple table-children (e.g., a column and a hierarchy with the same name). +- `--force` - bypass the dependents check. +- `--if-exists` - exit `0` without error if the object doesn't exist. Use this for idempotent CI/CD pipelines. +- `--dry-run` - preview the removal without applying it. +- `--save` / `--save-to ` - persist the change. +- `--serialization ` - override the serialization when saving (`tmdl`, `bim` (alias `tmsl`), `database.json`). ```bash te rm Sales/Revenue --save @@ -266,9 +281,17 @@ te rm Sales/OldMeasure --if-exists --save # Idempotent Move or rename a model object. Both source and destination are `` arguments. +`te mv` accepts: + +- `-t, --type ` - disambiguate when the source path matches multiple object kinds (e.g., a column and a hierarchy with the same name). +- `--save` / `--save-to ` - persist the change. +- `--serialization ` - override the serialization when saving (`tmdl`, `bim` (alias `tmsl`), `database.json`). +- `--force` - save even if the mutation introduces DAX validation errors. + ```bash -te mv Sales/Revenue Finance/Revenue --save # Move measure to another table -te mv Sales/Revenue Sales/TotalRevenue --save # Rename measure +te mv Sales/Revenue Finance/Revenue --save # Move measure to another table +te mv Sales/Revenue Sales/TotalRevenue --save # Rename measure +te mv Sales/Date Sales/CalendarDate -t Hierarchy --save # Disambiguate hierarchy from column ``` ### replace @@ -283,7 +306,7 @@ Find and replace text across model objects. Dry-run by default; add `--save` to - `--dry-run` - preview changes without applying. Default behavior. - `--save` - persist the mutation to the source location. Mutually exclusive with `--revert` and `--stage`. - `--save-to ` - save to a different path (implies `--save`). -- `--serialization ` - model serialization: `tmdl`, `bim`, `te-folder`. +- `--serialization ` - model serialization: `tmdl`, `bim` (alias `tmsl`), `database.json`. - `--force` - save even if the replacement introduces DAX validation errors. `--in expressions` walks every expression-bearing property: @@ -306,7 +329,7 @@ te replace "SUM" "SUMX" --regex --in expressions --save ### ls -List objects with filesystem-like navigation. Takes a `` argument supporting wildcards. Both model-level containers (`Tables`, `Measures`, `Columns`, `Hierarchies`, `Relationships`, `Roles`, `Perspectives`, `Cultures`) and table-scoped containers (`Sales/Measures`, `Sales/Columns`, …) are supported. +List objects with filesystem-like navigation. Takes a `` argument supporting wildcards. Both model-level containers and table-scoped containers are supported - see the [container keyword table](#containers-and-keywords) above for the full list. `te ls` accepts: @@ -380,6 +403,12 @@ Compare two models for structural differences. Returns the following exit codes: ```bash te diff ./model-v1 ./model-v2 te diff old.bim new.bim + +# Branch on exit code (POSIX sh): +te diff ./a ./b; case $? in 0) echo same;; 1) echo different;; *) echo error;; esac + +# Branch on exit code (PowerShell): +te diff ./a ./b; switch ($LASTEXITCODE) { 0 { 'same' } 1 { 'different' } default { 'error' } } ``` ### deps @@ -444,7 +473,7 @@ Run Best Practice Analyzer rules against a model. - `--fix` - apply fix expressions to auto-fix violations where possible. - `--save` - save the model back to source after applying fixes. - `--save-to ` - save the model to a different path after applying fixes. -- `--serialization ` - model serialization: `tmdl`, `bim`, `te-folder`. +- `--serialization ` - model serialization: `tmdl`, `bim` (alias `tmsl`), `database.json`. - `--fail-on ` - failure threshold: `error` (default) or `warning`. Exits with code `1` when violations meet the threshold. - `--ci ` - emit CI logging commands to stderr: `vsts` (Azure DevOps), `github` (GitHub Actions). - `--trx ` - write results as a VSTEST `.trx` file to the specified path. @@ -480,7 +509,7 @@ Rules loaded: 41 from 1 file(s) from bpa.rules config + built-in defaults + mode ### bpa rules -Manage BPA rule collections — list, inspect, initialize, and toggle rules in your local rules file or in model annotations. Built-in rules are read-only - to skip one without losing the rest, use `te bpa rules disable` (do not edit the built-in set directly). +Manage BPA rule collections - list, inspect, initialize, and toggle rules in your local rules file or in model annotations. Built-in rules are read-only - to skip one without losing the rest, use `te bpa rules disable` (do not edit the built-in set directly). Subcommands: @@ -546,11 +575,27 @@ te bpa rules init --rules-file ./MyRules.json te bpa rules init --force ``` +#### bpa rules add / set / rm / ignore / unignore + +Mutate the rules file (`add`, `set`, `rm`) or model-embedded ignore list (`ignore`, `unignore`). All three mutating subcommands operate on `--rules-file ` or `--model-rules` and refuse to touch built-in rule IDs. + +- `te bpa rules add ` - create a new rule. Pass each property with `-q -i ` pairs. Property names: `name`, `expression`, `scope`, `category`, `severity`, `description`, `fixExpression`. +- `te bpa rules set ` - update properties on an existing rule. Same `-q`/`-i` pairs as `add` (repeatable). +- `te bpa rules rm ` - remove a rule. +- `te bpa rules ignore ` - add a rule ID to the model's `BestPracticeAnalyzer_IgnoreRules` annotation. +- `te bpa rules unignore ` - remove a rule ID from the model's ignore list. + +```bash +te bpa rules add MY_RULE -q name -i "My rule" -q expression -i "Measure" -q severity -i 2 +te bpa rules set MY_RULE -q severity -i 3 +te bpa rules rm MY_RULE +``` + #### bpa rules disable Disable an individual built-in BPA rule. The rule ID is added to `bpa.disabledBuiltInRuleIds` in your CLI config. Subsequent gate runs (deploy, save, mutation) and `te bpa run` skip the disabled rule. -The command is idempotent — running `disable` against an already-disabled rule succeeds without modifying the config. It exits with code `1` if `` is not a built-in rule; use `te bpa rules list` to see valid built-in IDs. +The command is idempotent - running `disable` against an already-disabled rule succeeds without modifying the config. It exits with code `1` if `` is not a built-in rule; use `te bpa rules list` to see valid built-in IDs. ```bash te bpa rules disable TE3_BUILT_IN_DATE_TABLE_EXISTS @@ -570,6 +615,7 @@ Analyze VertiPaq storage statistics. `te vertipaq` accepts: +- `` - optional positional argument: a table name to filter the analysis to a single table. - `--columns`, `--relationships`, `--partitions`, `--all`. - `--detail` - show expanded columns (data/dict/hierarchy size breakdown, encoding, segments). - `--fields ` - comma-separated fields to display (e.g., `--fields name,card,size,%tbl,%db,bar`). Available fields vary by view. @@ -577,10 +623,12 @@ Analyze VertiPaq storage statistics. - `--import ` - load a previously exported `.vpax` file and analyze it offline. - `--obfuscate` - obfuscate names and expressions in exported VPAX. - `--top `, `--stats`, `--annotate`, `--save`. +- `--auth ` - auth method override when connecting to a remote model. ```bash -te vertipaq # Columns by size (default) -te vertipaq --all # Tables, columns, relationships, partitions +te vertipaq # Columns by size (default) +te vertipaq Sales # Stats limited to the Sales table +te vertipaq --all # Tables, columns, relationships, partitions te vertipaq --export stats.vpax te vertipaq --import stats.vpax # Analyze offline ``` @@ -615,7 +663,8 @@ Execute a DAX query against a deployed model. `te query` accepts: -- `-q, --query ` - inline query. +- `` - positional argument: the DAX query to execute. Equivalent to passing `-q`. Use whichever shape reads better; explicit `-q` wins if both are supplied. +- `-q, --query ` - inline query (named-flag form of the positional above). - `--file ` - query from file. - `--limit ` - default 100. - `-o, --output-file ` - write results to file (`.csv`, `.tsv`, `.json`, `.dax`). @@ -623,7 +672,8 @@ Execute a DAX query against a deployed model. - `--no-validate` - skip pre-execution DAX semantic validation. ```bash -te query -q "EVALUATE TOPN(5, 'Sales')" -s my-ws -d my-model +te query "EVALUATE TOPN(5, 'Sales')" -s my-ws -d my-model # Positional DAX +te query -q "EVALUATE TOPN(5, 'Sales')" -s my-ws -d my-model # Named-flag form te query --file query.dax --output-format json ``` @@ -688,6 +738,20 @@ Subcommands: | `sort` | Sort and re-assign IDs. | | [`init`](#macro-init) | Create an empty macros file at the resolved path. | +#### macro add / set / rm + +Mutate the macros file (`add`, `set`, `rm`). All three operate on `--macros ` (or the resolved macros file). + +- `te macro add ` - create a new macro. Provide the script body via `-e ""` (inline) or `-s ` (script file). Optional: `--tooltip `, `--contexts ` (where the macro applies, e.g., `Table,Measure`), `--enabled true|false`. +- `te macro set ` - update macro properties. Use `-q -i ` pairs (repeatable). Property names: `name`, `execute`, `enabled`, `tooltip`, `validContexts`. +- `te macro rm ` - remove a macro. + +```bash +te macro add MyMacro -e "Info(Selected.Measure.Name);" --tooltip "Print measure name" --contexts Measure +te macro set MyMacro -q tooltip -i "Updated tooltip" +te macro rm MyMacro +``` + #### macro init Create an empty macros file (`{"Actions":[]}`) at the configured path. Use this once when the resolved macros file does not yet exist. @@ -722,11 +786,11 @@ te macro run "Format DAX" --on "'Net Sales'[Sales Amount]" --save # DAX form w ### deploy -Deploy a semantic model to Power BI, Fabric, or Azure Analysis Services. +Deploy a semantic model to Power BI, Fabric, Azure Analysis Services, or on-prem SQL Server Analysis Services. `te deploy` accepts: -- `-s, --server` / `-d, --database` - target workspace and model. +- `-s, --server` / `-d, --database` - target server/workspace and model. A server name, FQDN, IP address, or MSOLAP connection string deploys to Analysis Services (Windows Integrated auth for on-prem); a workspace name or `powerbi://...` URL deploys to Power BI. See the [global options](#global-options) table for how `-s` is interpreted. - `--deploy-full` - overwrite + connections + partitions + shared expressions + roles + role members. - `--deploy-connections` - `--deploy-partitions` @@ -741,10 +805,11 @@ Deploy a semantic model to Power BI, Fabric, or Azure Analysis Services. - `--bpa-rules ` - repeatable; override `bpa.rules` from your CLI config for this single deploy. Built-in rules still apply unless `bpa.builtInRules` is `false`. - `--force` - skip interactive confirmation (required for CI). - `--ci ` - `vsts` or `github`. -- `--profile ` - one-shot use of a saved @te-cli-auth profile. +- `-p, --profile ` - one-shot use of a saved @te-cli-auth profile. ```bash te deploy ./model -s my-workspace -d my-model --force --ci github +te deploy ./model -s MY.SERVER.COM -d my-model --force # On-prem SSAS (Integrated auth) te deploy ./model --xmla script.tmsl # Generate TMSL only te deploy ./model --profile staging --force ``` @@ -758,12 +823,12 @@ Trigger a data refresh on a deployed model. `te refresh` accepts: -- `--type ` - `full`, `dataonly`, `automatic`, `calculate`, `clearvalues`, `defragment`, `add` (default: `automatic`). +- `--type ` - `full`, `dataonly` (alias `data-only`, `data`), `automatic` (alias `auto`), `calculate` (alias `calc`), `clearvalues` (alias `clear`), `defragment` (alias `defrag`), `add` (default: `automatic`). - `--table ` - refresh specific table(s); repeatable. - `--partition ` - refresh specific partition(s). - `--apply-refresh-policy` - apply the incremental refresh policy to determine which partitions are refreshed. - `--effective-date ` - set the effective date used by the refresh policy. -- `--max-parallelism ` - set the maximum number of partitions to refresh in parallel. +- `--max-parallelism ` - set the maximum number of partitions to refresh in parallel. Wraps the refresh in a TMSL `sequence` command. - `--dry-run` - output the TMSL script without executing. - `--no-progress`, `--trace [path]`. @@ -818,12 +883,14 @@ te test init --from-model --model ./my-model # Generate stubs from your measure Set (or display) the active connection for the current terminal session. See @te-cli-auth. ```bash -te connect # Show current active connection -te connect my-workspace my-model # Remote -te connect ./model # Local -te connect --local # Power BI Desktop (Windows) -te connect --profile prod # Activate a saved profile -te connect --clear # Clear the active connection (and any workspace mirror) +te connect # Show current active connection +te connect my-workspace my-model # Remote (positional) +te connect -s my-workspace -d my-model # Remote (named-flag form) +te connect ./model # Local +te connect --local # Power BI Desktop (Windows) +te connect --local my-report # Filter by report name (multiple PBI Desktop instances) +te connect --profile prod # Activate a saved profile +te connect --clear # Clear the active connection (and any workspace mirror) ``` #### Workspace mode (`-w` / `--workspace`) @@ -832,7 +899,7 @@ Pair a primary source with a secondary target so every subsequent `--save` mirro - `te connect -w ./src` - primary is remote; `./src` receives an initial TMDL export and mirrors every save. - `te connect ./src -w ` - primary is local; an initial deploy pushes the model to the workspace, and subsequent saves re-deploy automatically. -- `--workspace-format ` - choose the on-disk format when mirroring to a folder/file (e.g., `-w ./model.bim` infers BIM). +- `--workspace-format ` - choose the on-disk format when mirroring to a folder/file: `tmdl`, `bim` (alias `tmsl`), or `database.json`. When omitted, the format is inferred from the workspace target path (e.g., `-w ./model.bim` infers BIM). - `--workspace-auth ` - auth method for a remote workspace target when the primary is local. Defaults to `--auth` if set, else `auto`. - `--force` - required when the target already exists (non-empty folder, existing database). Without it, `te connect` shows an interactive `y/n` prompt with `n` as the safe default. @@ -864,10 +931,6 @@ te config init # Create default config te config set autoFormat true ``` -### license - -`te license` is reserved for the GA release and is not available in this preview build. The command is still wired up to the parser - so existing scripts that invoke it won't blow up at parse time - but every subcommand exits with status `1` and a "not available in this preview build" message. See the [Preview notice](xref:te-cli#preview-notice) on the overview page for the broader licensing outlook. - ### migrate Reference guide showing how legacy Tabular Editor 2 CLI flags map to the new CLI. Useful as a live lookup while porting a TE2-based pipeline. See @te-cli-migrate for the full migration guide. @@ -934,7 +997,7 @@ te completion fish | Exit | Meaning | | -- | -- | | `0` | Success. | -| `1` | Generic failure (invalid arguments, command failed, validation errors, auth failure, BPA gate failed at severity ≥ error). For `te diff`: differences found. | +| `1` | Generic failure (invalid arguments, command failed, validation errors, auth failure, BPA gate failed at severity >= error). For `te diff`: differences found. | | `2` | `te diff` only: an error occurred while comparing, so the difference status is unknown. | For fine-grained control in CI pipelines, combine exit codes with `--ci ` annotations and `--trx` results files - see @te-cli-cicd. diff --git a/content/features/te-cli/te-cli-config.md b/content/features/te-cli/te-cli-config.md index 9a5db398e..0acc82768 100644 --- a/content/features/te-cli/te-cli-config.md +++ b/content/features/te-cli/te-cli-config.md @@ -18,9 +18,9 @@ applies_to: The Tabular Editor CLI reads optional configuration from a JSON file. Configuration controls three things: -- **File paths** — where the CLI reads macros, BPA rules, and (optionally) the TE3 Desktop executable, and where to write the query log. -- **Behavioral defaults** — BPA gates, auto-format, validation. -- **Saved connection profiles** — the list of named profiles you can switch between. +- **File paths** - where the CLI reads macros, BPA rules, and (optionally) the TE3 Desktop executable, and where to write the query log. +- **Behavioral defaults** - BPA gates, auto-format, validation. +- **Saved connection profiles** - the list of named profiles you can switch between. The CLI is self-contained - it does not read from or write to any Tabular Editor 3 desktop install path. BPA rules and macros files must be set explicitly via this config (or initialized on demand with `te bpa rules init` / `te macro init`). @@ -78,7 +78,7 @@ The complete JSON config schema with all keys at their default values. Use this ```json { - "formatVersion": 1, + "formatVersion": 2, "macros": null, "autoFormat": false, "validateOnMutation": true, @@ -146,7 +146,7 @@ All BPA-related settings live under the `bpa` object and are addressed via dotte | `autoFormat` | `false` | Run the DAX Formatter on modified expressions after `te add` / `te set` / `te mv` / `te macro run`. Uses the in-house formatter by default; opt into the SQL BI web service via `formatOptions.useSqlBiDaxFormatter`. | | `validateOnMutation` | `true` | After a mutating command (`add`, `set`, `mv`, `replace --save`, `macro run`), check that every `Table[Column]` reference in the model still resolves. Catches dangling references introduced by renames or removals before they reach deploy. | | `bpa.onMutation` | `false` | Run a scoped BPA analysis after each mutating command (`set`, `add`, `mv`, `rm`, `macro run`). Only the affected table's objects are checked, not the whole model - useful for fast feedback during iterative edits. | -| `bpa.onDeploy` | `true` | Run the BPA gate before `te deploy` executes. The deploy is aborted if any rule fires at severity ≥ error. Bypass per-invocation with `--skip-bpa`, or auto-fix with `--fix-bpa`. | +| `bpa.onDeploy` | `true` | Run the BPA gate before `te deploy` executes. The deploy is aborted if any rule fires at severity >= error. Bypass per-invocation with `--skip-bpa`, or auto-fix with `--fix-bpa`. | | `bpa.onSave` | `true` | Run the BPA gate before `te save -o` writes to disk. Bypass per-invocation with `--skip-bpa` or `--force`. | | `bpa.builtInRules` | `true` | Include the curated built-in BPA rule set whenever the gate runs. Set to `false` to ignore built-ins entirely; the gate then runs only the rules configured via `bpa.rules` and any model-embedded rules. | | `bpa.disabledBuiltInRuleIds` | `null` | IDs of individual built-in rules to exclude from the gate. Mutated by `te bpa rules disable ` / `te bpa rules enable ` - prefer those over editing the array directly. | @@ -203,7 +203,7 @@ The BPA gate is the safety net that prevents a model with rule violations from b The gate loads BPA rules from `bpa.rules` and, by default, the built-in rule set (controlled by `bpa.builtInRules`). Built-in rules can be individually excluded via `bpa.disabledBuiltInRuleIds` - managed with `te bpa rules disable ` / `te bpa rules enable `. -When the gate fires and finds violations at severity ≥ `error`, the command fails with exit code `1` and a summary of the violations. Options to resolve: +When the gate fires and finds violations at severity >= `error`, the command fails with exit code `1` and a summary of the violations. Options to resolve: - `--fix-bpa` - apply the rule's `fixExpression` in memory for the deploy/save artifact; source files are not modified. - `--skip-bpa` - disable the gate for this one command. diff --git a/content/features/te-cli/te-cli-install.md b/content/features/te-cli/te-cli-install.md index 568023bad..0a858e352 100644 --- a/content/features/te-cli/te-cli-install.md +++ b/content/features/te-cli/te-cli-install.md @@ -131,7 +131,7 @@ te config set hidePreviewNotice true ## Shell completion -The CLI provides tab-completion scripts for **Bash**, **Zsh**, **PowerShell** and **Fish**. Pick the block that matches your shell — each one installs the completion persistently for new shell sessions. +The CLI provides tab-completion scripts for **Bash**, **Zsh**, **PowerShell** and **Fish**. Pick the block that matches your shell - each one installs the completion persistently for new shell sessions. ### Bash (macOS/Linux) diff --git a/content/features/te-cli/te-cli-limitations.md b/content/features/te-cli/te-cli-limitations.md index ce83dd5d4..860f13ae0 100644 --- a/content/features/te-cli/te-cli-limitations.md +++ b/content/features/te-cli/te-cli-limitations.md @@ -57,7 +57,7 @@ The CLI runs C# scripts (`te script`) against the same `Model` object you use in | Limitation | Notes / Workaround | | -- | -- | -| **`--serialization` cannot combine a serialization with a PBIP container** | The `--serialization` option on [`te save`](xref:te-cli-commands#save) treats `bim`, `tmdl`, `te-folder`, and `pbip` as mutually exclusive, so you cannot currently produce a PBIP container around a TMSL-serialized (`.bim`) model. Save TMDL inside PBIP, or save `.bim` outside a PBIP wrapper. | +| **`--serialization` cannot combine a serialization with a PBIP container** | The `--serialization` option on [`te save`](xref:te-cli-commands#save) treats `bim`, `tmdl`, `database.json`, and `pbip` as mutually exclusive, so you cannot currently produce a PBIP container around a TMSL-serialized (`.bim`) model. Save TMDL inside PBIP, or save `.bim` outside a PBIP wrapper. | ## Authentication diff --git a/content/features/te-cli/te-cli-migrate.md b/content/features/te-cli/te-cli-migrate.md index aeaf127a5..f3962d81b 100644 --- a/content/features/te-cli/te-cli-migrate.md +++ b/content/features/te-cli/te-cli-migrate.md @@ -57,15 +57,15 @@ A non-exhaustive summary of the most commonly used flags. Run `te migrate` for t | TE2 flag | New CLI equivalent | Notes | | -- | -- | -- | | `file` (positional) | `te ` or global `--model` | First positional arg on most commands. | -| `server`, `database` | `te connect ` or `te deploy ` | Server is no longer a global positional. | +| `server`, `database` | `te connect ` or `te deploy -s -d ` | Server is no longer a global positional; `te deploy` takes only `` positionally, with server and database as named flags. | | `-L` / `-LOCAL` | `te connect --local` | Windows only. | | `-S` / `-SCRIPT` | `te script -S ` or `-e "code"` | Supports multiple scripts, inline code, and stdin. Note: uppercase `-S` - lowercase `-s` is the global `--server` option. | | `-A` / `-ANALYZE` | `te bpa run --rules ` | Supports `--fail-on`, `--fix`, multiple rule files. | | `-AX` / `-ANALYZEX` | `te bpa run --rules ` (without `--model-rules`) | Excluding model-embedded rules is the new default. | | `-B` / `-BIM` | `te save -o --serialization bim` | | -| `-F` / `-FOLDER` | `te save -o --serialization te-folder` | After `-D`, TE2's `-F` means `-FULL` - see `--deploy-full`. | +| `-F` / `-FOLDER` | `te save -o --serialization database.json` | After `-D`, TE2's `-F` means `-FULL` - see `--deploy-full`. | | `-TMDL` | `te save -o --serialization tmdl` | TMDL is the default save format. | -| `-D` / `-DEPLOY` | `te deploy ` | Separate command with named options. | +| `-D` / `-DEPLOY` | `te deploy -s -d ` | Separate command with named options; only `` is positional. | | `-O` / `-OVERWRITE` | (default) or `--create-only` to opt out | Overwrite is the default in the new CLI. | | `-C` / `-CONNECTIONS` | `te deploy --deploy-connections` | | | `-P` / `-PARTITIONS` | `te deploy --deploy-partitions` | | diff --git a/content/features/te-cli/te-cli.md b/content/features/te-cli/te-cli.md index 5c091878d..2e50c2f36 100644 --- a/content/features/te-cli/te-cli.md +++ b/content/features/te-cli/te-cli.md @@ -26,9 +26,9 @@ Unlike the Windows-only `TabularEditor.exe` command-line options (TE2) - which w Three design pillars run through every command: -- **Structured output** — JSON, CSV, TMDL, TMSL alongside default human-readable text. -- **Non-interactive mode** — a global `--non-interactive` flag that disables prompts and fails fast. -- **Clear errors** — written to stderr with predictable exit codes. +- **Structured output** - JSON, CSV, TMDL, TMSL alongside default human-readable text. +- **Non-interactive mode** - a global `--non-interactive` flag that disables prompts and fails fast. +- **Clear errors** - written to stderr with predictable exit codes. Together they make the same binary work well for three very different audiences: