diff --git a/content/features/Command-line-Options.md b/content/features/Command-line-Options.md index 863ae6f0..7060e892 100644 --- a/content/features/Command-line-Options.md +++ b/content/features/Command-line-Options.md @@ -56,7 +56,7 @@ The Tabular Editor CLI (`te`) is the cross-platform successor to `TabularEditor. | **Model editing in pipeline** | | | | Run C# scripts | `-S` flag | `te script` - multiple scripts, inline code, stdin, `--dry-run`, preprocessor symbols (`TECLI`) | | Run macros | No | `te macro run` with `--on ` context | -| Set/get properties | No | `te get`, `te set`, `te add`, `te rm`, `te mv`, `te replace` | +| Set/get properties | No | `te get`, `te set`, `te add`, `te rm`, `te mv` | | DAX formatting | No | `te format` - all expressions or single object, DAX and M | | **Inspection** | | | | List model objects | No | `te ls` with wildcard path filters, `--type`, `--paths-only`, `--output-format bim` | diff --git a/content/features/te-cli/te-cli-automation.md b/content/features/te-cli/te-cli-automation.md index 53c76fb7..2748f6a6 100644 --- a/content/features/te-cli/te-cli-automation.md +++ b/content/features/te-cli/te-cli-automation.md @@ -26,7 +26,7 @@ Use `--output-format` to switch any command between text (human-readable) and ma | -- | -- | -- | | `text` (default) | Human-readable use | Plain text on stdout regardless of whether the stream is a TTY or piped. | | `json` | Machine-readable use | Always valid JSON to stdout. Use `--error-format json` if you also want machine-readable errors on stderr. | -| `csv` | Tabular results (`query`, `bpa run`, `bpa rules`, `vertipaq`, `validate`, `test`, `refresh`, `profile list`, `session list`, `find`, `replace`, `get`, `ls`) | RFC 4180 escaping. | +| `csv` | Tabular results (`query`, `bpa run`, `bpa rules`, `vertipaq`, `validate`, `test`, `refresh`, `profile list`, `session list`, `find`, `get`, `ls`) | RFC 4180 escaping. | | `tmsl` (alias `bim`) | Whole-object TMSL/BIM serialization | Accepted by `te get` and `te list`. | | `tmdl` | Whole-object TMDL serialization | Accepted by `te get` only (single object). | @@ -179,7 +179,7 @@ The resulting TMSL can be reviewed in a pull request, committed, executed by the A handful of small idioms that come up often when composing `te` commands in scripts or pipelines: - **Idempotent creates and removes.** `te add Sales/Marker -t Measure -i "0" --if-not-exists --save` and `te remove Sales/OldMeasure --if-exists --save` both exit `0` whether or not the object existed - safe to re-run in CI. -- **Dry-run diffs.** `te replace` is dry-run by default; add `--save` only when you're satisfied with the preview. +- **Nothing persists without `--save`.** Mutating commands (`te add`, `te set`, `te move`, `te remove`, `te format`, `te script`, `te macro run`) apply the change in memory, report what they did, and then print `Changes not saved. Use --save to persist.` Run one bare to confirm it resolves the objects you expect, then re-run with `--save`. `te remove --dry-run` goes further and reports what would be removed without applying anything. - **Emit TMSL for review.** `te deploy ./model --xmla deploy.tmsl` produces the deployment script without touching the server - useful for DBA review or manual apply. - **Path-only output.** `te list --paths-only` and `te find --paths-only` emit one object path per line, ideal for piping to `xargs`, `te get`, or `te set`. The model-level containers (`te list Measures`, `te list Columns`) compose well with this for whole-model sweeps. - **Benchmarking queries.** `te query --trace --cold --runs 5` runs a DAX query with cold cache, five iterations, and captures FE/SE trace events. diff --git a/content/features/te-cli/te-cli-commands.md b/content/features/te-cli/te-cli-commands.md index b68e66c0..f82ed720 100644 --- a/content/features/te-cli/te-cli-commands.md +++ b/content/features/te-cli/te-cli-commands.md @@ -168,16 +168,6 @@ positional `` argument → `--model` global flag → `--server`/`--databa ## Model I/O -### load - -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 -te load model.bim # BIM file -te load -s MyWorkspace -d MyModel # Remote workspace -``` - ### save Save a model to disk. Use it to write a remote workspace model to local files, convert formats, or persist edits back to the source. @@ -203,16 +193,6 @@ te save -o ./out -s my-workspace -d my-model --skip-validation # Fast download > [!TIP] > Use `te save -o -s -d ` to download a remote model to disk. Pair with `--skip-validation` for the fastest passthrough when you only need the bytes (no DAX semantic analysis). -### open - -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 # 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 Create a new empty semantic model at the given path. Defaults to a TMDL model in `PowerBI` compatibility mode at compatibility level 1702. @@ -321,37 +301,6 @@ te move Sales/Revenue Sales/TotalRevenue --save # Rename measure te move Sales/Date Sales/CalendarDate -t Hierarchy --save # Disambiguate hierarchy from column ``` -### replace - -Find and replace text across model objects. Dry-run by default; add `--save` to apply. - -`te replace` accepts: - -- `--in ` - scope: `names`, `expressions`, `descriptions`, `displayFolders`, `formatStrings`, `annotations`, `all` (default: `all`). -- `--regex` - treat the find pattern as a regular expression. -- `--case-sensitive` - enable case-sensitive matching. -- `--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` (alias `tmsl`), `database.json`. -- `--force` - save even if the replacement introduces DAX validation errors. - -`--in expressions` walks every expression-bearing property: - -- **Measure**: `Expression`, `DetailRowsExpression` -- **KPI**: `TargetExpression`, `StatusExpression`, `TrendExpression` -- **Partition**: source M, polling M -- **Table permission**: `FilterExpression` -- **Calculation group**: selection expressions -- **Calculated column**: DAX expression - -Adding new expression-shaped properties to the model surfaces them automatically. - -```bash -te replace "OldTable" "NewTable" --in expressions --save -te replace "SUM" "SUMX" --regex --in expressions --save -``` - ## Inspection ### list @@ -411,7 +360,7 @@ Search for text across model objects. `te find` accepts: -- `--in ` - as per `te replace` (default `all`). +- `--in ` - scope: `names`, `expressions`, `descriptions`, `displayFolders`, `formatStrings`, `annotations`, `all` (default: `all`). - `--regex`, `--case-sensitive`, `--paths-only`. - `--no-multiline` - collapse multi-line match context to a single line. Text output only. diff --git a/content/features/te-cli/te-cli-config.md b/content/features/te-cli/te-cli-config.md index 033cd1fd..6c2f560b 100644 --- a/content/features/te-cli/te-cli-config.md +++ b/content/features/te-cli/te-cli-config.md @@ -18,7 +18,7 @@ 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. +- **File paths** - where the CLI reads macros and BPA rules, 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. @@ -109,7 +109,6 @@ The complete JSON config schema with all keys at their default values. Use this "disableTelemetry": false, "queryLog": null, - "te3ExePath": null, "profiles": {} } @@ -123,7 +122,6 @@ Set these in your config to avoid passing the same paths on every command. Per-c | -- | -- | | `macros` | Explicit path to a macros JSON file (typically `MacroActions.json`). Resolved by every `te macro` command. Point at a shared file (network share, repo-local, or even the TE3 desktop file) to reuse the same set of macros across machines and between the CLI and TE3 Desktop. | | `bpa.rules` | Ordered list of paths or URLs to BPA rule files. `te bpa run` and the deploy/save gate load **every** existing entry; `te bpa rules list` and `te config paths` use the first existing entry. Comma-separated values on `te config set bpa.rules ...` are split into the array. | -| `te3ExePath` | Explicit path to the Tabular Editor 3 Desktop executable (`TabularEditor.exe`). Used **only** by `te open` to launch the desktop app; safe to leave unset on Linux/macOS or when you don't use `te open`. If unset, `te open` falls back to a `PATH` lookup. | | `queryLog` | Path to a log file where every `te query` invocation appends its query text and execution metadata. Useful for audit trails or analyzing query patterns over time. Supports `~` for the home directory (e.g., `~/.config/te/queries.log`). | ### Path resolution priority @@ -145,7 +143,7 @@ All BPA-related settings live under the `bpa` object and are addressed via dotte | Key | Default | Description | | -- | -- | -- | | `autoFormat` | `false` | Run the DAX Formatter on modified expressions after `te add` / `te set` / `te move` / `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. | +| `validateOnMutation` | `true` | After a mutating command (`add`, `set`, `mv`, `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.onSave` | `true` | Run the BPA gate before `te save -o` writes to disk. Bypass per-invocation with `--skip-bpa` or `--force`. | @@ -226,7 +224,7 @@ Both `bpa.builtInRules` and `bpa.disabledBuiltInRuleIds` apply consistently to t ## Post-mutation behavior -When you run a mutating command (`te add`, `te set`, `te move`, `te replace --save`, `te macro run`), the CLI performs these checks automatically: +When you run a mutating command (`te add`, `te set`, `te move`, `te macro run`), the CLI performs these checks automatically: 1. **TOM errors** are always surfaced. Invalid DAX or M in measures, columns, partitions, or calculation items always fails the command. 2. **Schema validation** (`validateOnMutation`, default `true`) verifies that `Table[Column]` references in DAX still resolve, cross-checking metadata consistency. @@ -245,7 +243,6 @@ Use the following CLI-specific environment variables for paths, behavior, and di | `TE_MACROS_PATH` | Override the macros file path (second in resolution order - see above). Read by `te macro` commands. | | `TE_BPA_RULES` | Override the BPA rules file/URL list used by `te bpa run` and `te bpa rules` subcommands. | | `TE_BPA_CONFIG` | Override the path to the BPA gate config (`.te-bpa.json`) the deploy/save gate reads. | -| `TE3_EXE_PATH` | Path to the Tabular Editor 3 desktop binary. Used **only** by `te open`; safe to leave unset on Linux/macOS or when you don't use `te open`. Falls back to `PATH` lookup. | | `TE_DEBUG` | Set to `1` to enable debug logging globally (same as `--debug` or `debug: true` in config). | | `NO_SPINNER` | Set to `1` or `true` to disable animated progress indicators (alternative to `spinner: false` in config). | | `CI` | Auto-detected. When `1` or `true`, the CLI disables the spinner and switches to plain output. Most CI runners set this automatically. | diff --git a/content/features/te-cli/te-cli-migrate.md b/content/features/te-cli/te-cli-migrate.md index f3962d81..1f0f7564 100644 --- a/content/features/te-cli/te-cli-migrate.md +++ b/content/features/te-cli/te-cli-migrate.md @@ -26,7 +26,7 @@ TE2 compatibility mode is activated in any of three ways: 1. **Binary name.** Rename `te` to `te2` (or symlink it) and the CLI runs in TE2-exact mode. This is the drop-in replacement path: swap `TabularEditor.exe` for `te2` in your existing pipeline and the same arguments work. 2. **Environment variable.** Set `TE_COMPAT=te2` before invoking `te` to force TE2 mode. -3. **Auto-detection.** If the first argument isn't a `te` subcommand (`load`, `deploy`, …) and at least one recognized TE2 flag appears somewhere in the argument list, the CLI auto-routes to TE2 mode. This means most existing TE2 invocations work without any changes. +3. **Auto-detection.** If the first argument isn't a `te` subcommand (`deploy`, `validate`, …) and at least one recognized TE2 flag appears somewhere in the argument list, the CLI auto-routes to TE2 mode. This means most existing TE2 invocations work without any changes. ```bash # All three are equivalent - each runs in TE2 mode diff --git a/content/features/te-cli/te-cli-skill.md b/content/features/te-cli/te-cli-skill.md index 8cc3a282..36a52247 100644 --- a/content/features/te-cli/te-cli-skill.md +++ b/content/features/te-cli/te-cli-skill.md @@ -28,7 +28,7 @@ A skill is a Markdown file an AI agent loads on demand based on your prompt. Its The skill teaches the agent the full `te` surface: -- every `te` command across all families - load, save, init, deploy, refresh, bpa, validate, query, script, format, and more +- every `te` command across all families - save, init, deploy, refresh, bpa, validate, query, script, format, and more - authentication patterns - interactive, service principal with secret or certificate, environment variables, managed identity - object path grammar - slash form, DAX form, and wildcards - the staging model - `--save`, `--stage`, and `--revert` behavior diff --git a/content/features/te-cli/te-cli.md b/content/features/te-cli/te-cli.md index 1a7384ec..2003492b 100644 --- a/content/features/te-cli/te-cli.md +++ b/content/features/te-cli/te-cli.md @@ -47,7 +47,7 @@ See @te-cli-commands for a full command reference with syntax, options, and exam | Family | What it does | Example commands | | -- | -- | -- | -| [Model I/O](xref:te-cli-commands#model-io) | Load, save, convert, initialize models | [`te load`](xref:te-cli-commands#load), [`te save`](xref:te-cli-commands#save), [`te init`](xref:te-cli-commands#init) | +| [Model I/O](xref:te-cli-commands#model-io) | Save, convert, initialize models | [`te save`](xref:te-cli-commands#save), [`te init`](xref:te-cli-commands#init) | | [Model Editing](xref:te-cli-commands#model-editing) | Get/set properties, add/remove/move objects | [`te set`](xref:te-cli-commands#set), [`te add`](xref:te-cli-commands#add), [`te remove`](xref:te-cli-commands#remove), [`te move`](xref:te-cli-commands#move) | | [Inspection](xref:te-cli-commands#inspection) | List objects, search, diff, dependency analysis | [`te list`](xref:te-cli-commands#list), [`te find`](xref:te-cli-commands#find), [`te diff`](xref:te-cli-commands#diff), [`te deps`](xref:te-cli-commands#deps) | | [Analysis & Quality](xref:te-cli-commands#analysis-and-quality) | Validate, run BPA, format DAX, analyze storage | [`te validate`](xref:te-cli-commands#validate), [`te bpa run`](xref:te-cli-commands#bpa-run), [`te format`](xref:te-cli-commands#format), [`te vertipaq`](xref:te-cli-commands#vertipaq) |