te-cli

# Tabular Editor CLI (`te`)

To get the `te` CLI yourself (as the agent), see [references/get-te-cli.md](references/get-te-cli.md).

The `te` CLI is a single self-contained binary that loads, edits, validates, deploys, refreshes, and tests semantic models against TMDL/BIM files, Power BI Desktop, and cloud workspaces (Power BI, Fabric, Azure AS, SSAS). It is built on the same TOMWrapper that powers Tabular Editor 3, so model edits behave like the desktop app.

**Always pass `--output-format json`** when driving `te` programmatically. The default text/table output uses tables and ANSI styling that mangle in agent transcripts; JSON is parseable and avoids rendering issues.

**Limited public preview.** Preview builds stop functioning after 2026-09-30. No license is required during preview. Issues and feedback: https://github.com/TabularEditor/CLI

**Not the TE2 CLI.** This is a different product from the legacy Windows-only `TabularEditor.exe` (TE2). If the user invokes TE2 flag syntax (`-D`, `-S`, `-A`, `-B`, `-TMDL`, `-O`, `-C`, `-V`, `-G`), route it through the compat layer or invoke `TabularEditor.exe` directly. See `references/te2-migration.md`.

## When to use this skill

- The user mentions "te CLI", "the new Tabular Editor CLI", or runs a `te <command>` in a terminal
- The user wants to scaffold, inspect, edit, validate, deploy, refresh, query, or test a semantic model from the terminal on any OS
- The user wants to convert TMDL, BIM, or PBIP, run BPA, or format DAX from the command line
- The user is migrating CI/CD pipelines from `TabularEditor.exe` (TE2) to `te`

## When NOT to use this skill

- The user explicitly wants to run `TabularEditor.exe` natively (TE2); use that product directly
- The user asks about Tabular Editor 3 desktop UI features (Preferences.json, MacroActions.json, Layouts.json); consult https://docs.tabulareditor.com/
- The user wants help authoring a C# script body or a BPA rule expression itself rather than running it; use the `c-sharp-scripting` and `bpa-rules` skills

## Critical general rules

- First use in a session: run `te --version` and `te auth status`. If not authenticated, ask the user to run `te auth login`.
- Run `te --help` and `te <command> --help` the first time composing a command; flags are still evolving during preview.
- `te connect` state is per-shell-session and does NOT survive across separate Bash tool calls (each call is a fresh shell). Pass `-m <model>` (and `-s`/`-d` for remote) on every command, or set `TE_SESSION=<name>` before the first call to share state.
- MPartition path asymmetry: `te add` for an M partition uses `<Table>/<Partition>`, but every other command (`te rm`, `te get`, `te ls`, `te mv`, `te set`) uses `<Table>/Partitions/<Partition>`.
- Mutations stage in memory by default. `te set`, `te add`, `te rm`, `te mv`, `te replace`, `te format`, `te script`, `te macro run`, `te incremental-refresh set/remove` need `--save` to persist (unless `interactiveEditMode` is set to `save`).
- The BPA gate is ON by default for `te deploy` and `te save`. Bypass deliberately: `--skip-bpa`, `--fix-bpa`, or `bpa.onDeploy` / `bpa.onSave` config (keys are nested under `bpa.`, not flat).
- In CI: pass `--non-interactive` and `--force`. `te deploy` prompts with `n` as the safe default and hangs pipelines without `--force`.
- Never put secrets on the command line (visible in `ps` and shell history). Use `--auth env` with `AZURE_CLIENT_ID`/`AZURE_CLIENT_SECRET`/`AZURE_TENANT_ID`, stdin (`-`), or `--auth managed-identity`.
- Avoid destructive operations without explicit direction: `te rm`, `te mv`, `te deploy --create-only`, `te save --force`, `te connect --clear`. If a command is blocked by permissions, stop and ask.

## Staging model (`--save` / `--stage` / `--revert`)

Every mutating command runs through a staging dispatcher: edits (`set`, `add`, `rm`, `mv`, `replace`), DAX/M (`format`), TOM (`script`, `macro run`), refresh policy, and BPA `--fix`.

By default edits stage in memory and are discarded on exit. Pass `--save` to persist. The default is configurable with `te config set interactiveEditMode <mode>`:

- `stage` (default): keep changes in memory; persist with explicit `--save`
- `save`: auto-persist after each successful mutation
- `revert`: auto-roll-back after each mutation (safe audit/dry-run style)

Inside `te interactive`, `--save`, `--stage`, and `--revert` are available per command and mutually exclusive. `--save-to <path>` writes the mutation to a different location without overwriting the source. `--force` on `te script` / `te save` lets a mutation persist even when it introduces NEW DAX validation errors; the default save gate refuses to persist if the mutation introduces new errors (pre-existing errors do not block).

## Quickstart

```bash
te --version && te auth status          # 0. check install + auth
te auth login                           # 1. authenticate (browser); cached
te init ./my-model                      # 2. scaffold (PowerBI mode, TMDL, compat 1702)
te load ./model                         # 3. load + summary; then `te ls`, `te ls Sales`
te find "Revenue" --in names -m ./model # 4. search (names | expressions | descriptions | all)
te get Sales/Revenue -q expression -m ./model      # 5. read a measure's DAX
te bpa run --fail-on error --ci github -m ./model   # 6. BPA gate
te format --save -m ./model             # 7. format all DAX
te query -q "EVALUATE TOPN(5, 'Sales')" -s ws -d model    # 8. query
te save -o ./out --serialization tmdl -m ./model    # 9. save / convert (tmdl|bim|pbip|te-folder)
te deploy ./model -s ws -d model --force --ci github      # 10. deploy
te refresh --type full -s ws -d model   # 11. refresh
```

`te connect <ws> <model>` sets an active connection for interactive terminals, but it does not persist across separate Bash tool calls. In agentic or scripted use, pass `-m`/`-s`/`-d` explicitly every command (or set `TE_SESSION`).

## Common operations

The highest-frequency tasks in th