Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/features/Command-line-Options.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <object>` 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` |
Expand Down
4 changes: 2 additions & 2 deletions content/features/te-cli/te-cli-automation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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). |

Expand Down Expand Up @@ -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.
Expand Down
53 changes: 1 addition & 52 deletions content/features/te-cli/te-cli-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,16 +168,6 @@ positional `<model>` 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.
Expand All @@ -203,16 +193,6 @@ te save -o ./out -s my-workspace -d my-model --skip-validation # Fast download
> [!TIP]
> Use `te save -o <path> -s <workspace> -d <model>` 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.
Expand Down Expand Up @@ -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>` - 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 <path>` - save to a different path (implies `--save`).
- `--serialization <fmt>` - 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
Expand Down Expand Up @@ -411,7 +360,7 @@ Search for text across model objects.

`te find` accepts:

- `--in <scope>` - as per `te replace` (default `all`).
- `--in <scope>` - 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.

Expand Down
9 changes: 3 additions & 6 deletions content/features/te-cli/te-cli-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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": {}
}
Expand All @@ -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
Expand All @@ -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`. |
Expand Down Expand Up @@ -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.
Expand All @@ -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. |
Expand Down
2 changes: 1 addition & 1 deletion content/features/te-cli/te-cli-migrate.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion content/features/te-cli/te-cli-skill.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion content/features/te-cli/te-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down
Loading