|
| 1 | +--- |
| 2 | +uid: te-cli-auth |
| 3 | +title: Authentication and Connections |
| 4 | +author: Peer Grønnerup |
| 5 | +updated: 2026-05-06 |
| 6 | +applies_to: |
| 7 | + products: |
| 8 | + - product: Tabular Editor 2 |
| 9 | + none: true |
| 10 | + - product: Tabular Editor 3 |
| 11 | + none: true |
| 12 | + - product: Tabular Editor CLI |
| 13 | + full: true |
| 14 | +--- |
| 15 | +# Authentication and Connections |
| 16 | + |
| 17 | +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] |
| 18 | + |
| 19 | +The Tabular Editor CLI authenticates to Power BI Service, Microsoft Fabric, and Azure Analysis Services using the same Power BI Desktop client ID that Tabular Editor 3 uses. Tokens are cached locally so you authenticate once and re-run commands silently until the refresh token expires (typically 90 days). |
| 20 | + |
| 21 | +## Authentication methods |
| 22 | + |
| 23 | +The CLI supports the full Azure Identity credential chain: |
| 24 | + |
| 25 | +| Method | When to use | `--auth` value | |
| 26 | +| -- | -- | -- | |
| 27 | +| Interactive browser | Local development - opens the system browser | `interactive` (default) | |
| 28 | +| Service principal (client secret) | Automation, CI/CD, headless / SSH / WSL | `spn` (with `-u / -p / -t`) or `env` | |
| 29 | +| Service principal (certificate) | Automation with certificate-based auth | `spn` (with `-u / -t / --certificate`) | |
| 30 | +| Environment variables | `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID` | `env` | |
| 31 | +| Managed identity | Azure VMs, Azure Container Apps, Azure Functions | `managed-identity` | |
| 32 | + |
| 33 | +> [!NOTE] |
| 34 | +> `--auth` is a **global** option, available on every `te` command - not just `te auth login`. Pass it to [`te deploy`](xref:te-cli-commands#deploy), [`te refresh`](xref:te-cli-commands#refresh), [`te query`](xref:te-cli-commands#query), [`te connect`](xref:te-cli-commands#connect), or any other command that connects to a remote endpoint, to override the default chain for that invocation. The default (`auto`) tries environment credentials first, then falls back to the cached or interactive browser login. |
| 35 | +
|
| 36 | +For headless, SSH, WSL, or devcontainer scenarios, use a service principal - `te auth login -u <id> -p <secret> -t <tenant>` (or `--certificate`). The login is cached, so subsequent commands acquire tokens silently with `--auth auto`. |
| 37 | + |
| 38 | +## `te auth login` |
| 39 | + |
| 40 | +Authenticate and cache the result for subsequent commands: |
| 41 | + |
| 42 | +```bash |
| 43 | +# Browser-based interactive login (default) |
| 44 | +te auth login |
| 45 | + |
| 46 | +# Service principal with client secret |
| 47 | +te auth login -u "$AZURE_CLIENT_ID" -p "$AZURE_CLIENT_SECRET" -t "$AZURE_TENANT_ID" |
| 48 | + |
| 49 | +# Service principal - read secret from stdin |
| 50 | +echo "$AZURE_CLIENT_SECRET" | te auth login -u "$AZURE_CLIENT_ID" -p - -t "$AZURE_TENANT_ID" |
| 51 | + |
| 52 | +# Service principal with certificate |
| 53 | +te auth login -u "$AZURE_CLIENT_ID" -t "$AZURE_TENANT_ID" --certificate ./sp.pfx --certificate-password "$CERT_PASSWORD" |
| 54 | + |
| 55 | +# Managed identity (Azure-hosted) |
| 56 | +te auth login --identity |
| 57 | +``` |
| 58 | + |
| 59 | +After a successful service-principal login the CLI **caches the credentials** so every subsequent `te` command can acquire tokens silently - no need to re-pass `-u / -p / -t` or set the `AZURE_CLIENT_*` environment variables. Pass `--save=false` for a one-shot login that doesn't update the cache, or run `te auth logout` to clear it. |
| 60 | + |
| 61 | +> [!WARNING] |
| 62 | +> Passing secrets directly on the command line exposes them to process listings and shell history. Prefer the `AZURE_CLIENT_SECRET` environment variable, or pipe the secret via stdin with `-p -`. |
| 63 | +
|
| 64 | +## `te auth status` |
| 65 | + |
| 66 | +Display the current authentication state without opening a browser: |
| 67 | + |
| 68 | +```bash |
| 69 | +te auth status |
| 70 | +te auth status --output-format json |
| 71 | +``` |
| 72 | + |
| 73 | +This returns an exit code of `0` when a valid session exists, `1` when not logged in or expired. |
| 74 | + |
| 75 | +## `te auth logout` |
| 76 | + |
| 77 | +Clear all cached credentials: |
| 78 | + |
| 79 | +```bash |
| 80 | +te auth logout |
| 81 | +``` |
| 82 | + |
| 83 | +## Credential storage |
| 84 | + |
| 85 | +The CLI stores access/refresh tokens and service-principal records in the **OS-native secure store** by default. A `0600` file fallback is selected automatically only when the OS keystore is unavailable (e.g., headless Linux without libsecret/D-Bus). |
| 86 | + |
| 87 | +| Platform | Backend | Storage location | |
| 88 | +| -- | -- | -- | |
| 89 | +| Windows | DPAPI | Per-user, managed by MSAL | |
| 90 | +| Linux | libsecret (system keyring) | Per-user, managed by MSAL | |
| 91 | +| macOS | Keychain | Service `com.tabulareditor.cli.*`, account `te-msal-cache.bin` | |
| 92 | +| Any (fallback) | `0600` file | `~/.te-cli/te-msal-cache.bin` and per-key `.bin` blobs | |
| 93 | + |
| 94 | +Interactive browser and service-principal flows share the same cache; MSAL's account model distinguishes them - there are no separate `auth-record*.json` sidecar files. Run any command with `--debug` to see which backend was selected at startup. |
| 95 | + |
| 96 | +`te auth logout` clears every cached record (both the MSAL token cache and any SPN blobs) regardless of which backend is in use. |
| 97 | + |
| 98 | +## `te connect` - set the active connection |
| 99 | + |
| 100 | +`te connect` persists an active connection for the current terminal session. Subsequent commands that take `-s` / `-d` can omit them: |
| 101 | + |
| 102 | +```bash |
| 103 | +# Remote workspace |
| 104 | +te connect my-workspace my-model |
| 105 | + |
| 106 | +# Local TMDL folder, .bim file, or .SemanticModel container |
| 107 | +te connect ./my-model |
| 108 | + |
| 109 | +# Connect to a running Power BI Desktop instance (Windows only) |
| 110 | +te connect --local |
| 111 | + |
| 112 | +# Show the active connection |
| 113 | +te connect |
| 114 | + |
| 115 | +# Clear the active connection (and any workspace mirror) |
| 116 | +te connect --clear |
| 117 | +``` |
| 118 | + |
| 119 | +Active-connection state is per-terminal-session: opening a new terminal starts fresh. |
| 120 | + |
| 121 | +### Workspace mode (`-w` / `--workspace`) |
| 122 | + |
| 123 | +`te connect -w <target>` pairs a primary source with a secondary mirror so every subsequent `--save` writes to both. Use it to keep a local working copy of a remote model in sync, or to push local edits to a workspace as you save: |
| 124 | + |
| 125 | +```bash |
| 126 | +# Mirror remote workspace ↔ local TMDL folder |
| 127 | +te connect Finance "Revenue Model" -w ./revenue-model |
| 128 | + |
| 129 | +# Mirror local source ↔ remote workspace (initial deploy + auto-redeploy on save) |
| 130 | +te connect ./revenue-model -w Finance "Revenue Model" |
| 131 | +``` |
| 132 | + |
| 133 | +Save order is always **local first, then remote**, so the on-disk copy reflects the latest user change even if the server push fails. See @te-cli-commands#workspace-mode-w--workspace for `--workspace-format`, overwrite semantics, and clearing the mirror. |
| 134 | + |
| 135 | +## Connecting to different clouds |
| 136 | + |
| 137 | +The CLI detects the correct scope from the server URL for: |
| 138 | + |
| 139 | +- Power BI Service and Fabric (commercial, US Gov, China, Germany clouds) |
| 140 | +- Azure Analysis Services (`asazure://...`) |
| 141 | +- Local SSAS (`localhost`, named instances - Windows only) |
| 142 | + |
| 143 | +Pass an XMLA endpoint, workspace name, or `powerbi://` URL as `--server`: |
| 144 | + |
| 145 | +```bash |
| 146 | +te connect "powerbi://api.powerbi.com/v1.0/myorg/Finance" "Revenue Model" |
| 147 | +te connect "powerbi://api.powerbi.com/v1.0/SpaceParts/Finance" "Revenue Model" |
| 148 | +te connect "asazure://westeurope.asazure.windows.net/myaas" "MyModel" |
| 149 | +te connect localhost "AdventureWorks" |
| 150 | +``` |
| 151 | + |
| 152 | +## Connection profiles |
| 153 | + |
| 154 | +For repeated use of the same connection - especially when you deploy to multiple environments - save named profiles: |
| 155 | + |
| 156 | +```bash |
| 157 | +# Save remote and local profiles |
| 158 | +te profile set prod -s my-workspace -d my-model --description "Production" |
| 159 | +te profile set dev --model ./model --description "Local dev TMDL" |
| 160 | + |
| 161 | +# List and inspect |
| 162 | +te profile list |
| 163 | +te profile show prod |
| 164 | + |
| 165 | +# Use a profile as the active connection |
| 166 | +te connect --profile prod |
| 167 | + |
| 168 | +# One-shot use without changing the active connection |
| 169 | +te deploy ./model --profile staging --force |
| 170 | +``` |
| 171 | + |
| 172 | +Profiles can also carry behavioral overrides that take effect whenever the profile is active: |
| 173 | + |
| 174 | +```bash |
| 175 | +# In dev, disable the BPA gate on deploy and loosen validation |
| 176 | +te profile set dev --bpa-on-deploy false --validate-on-mutation false |
| 177 | + |
| 178 | +# In prod, force auto-format before any mutation |
| 179 | +te profile set prod --auto-format true |
| 180 | +``` |
| 181 | + |
| 182 | +See @te-cli-config for the full list of overridable behaviors. |
| 183 | + |
| 184 | +## Non-interactive authentication |
| 185 | + |
| 186 | +For CI/CD pipelines, agents, or any unattended context, avoid interactive flows by combining: |
| 187 | + |
| 188 | +- The `--non-interactive` global flag (fails fast instead of prompting). |
| 189 | +- One of the non-interactive auth methods: `env`, `managed-identity`, or explicit service principal credentials. |
| 190 | + |
| 191 | +Environment-based example for a pipeline: |
| 192 | + |
| 193 | +```bash |
| 194 | +export AZURE_CLIENT_ID="your-app-id" |
| 195 | +export AZURE_CLIENT_SECRET="your-client-secret" |
| 196 | +export AZURE_TENANT_ID="your-tenant-id" |
| 197 | + |
| 198 | +te deploy ./model -s my-workspace -d my-model \ |
| 199 | + --auth env \ |
| 200 | + --non-interactive \ |
| 201 | + --force \ |
| 202 | + --ci github |
| 203 | +``` |
| 204 | + |
| 205 | +See @te-cli-cicd for complete GitHub Actions and Azure DevOps Pipelines examples. |
| 206 | + |
| 207 | +## Authentication environment variables |
| 208 | + |
| 209 | +The CLI honors the standard Azure.Identity environment variables when you use `--auth env` (and as part of the `auto` chain): |
| 210 | + |
| 211 | +| Variable | Purpose | |
| 212 | +| -- | -- | |
| 213 | +| `AZURE_CLIENT_ID` | Service principal application ID. | |
| 214 | +| `AZURE_CLIENT_SECRET` | Service principal client secret. Used together with `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`. | |
| 215 | +| `AZURE_TENANT_ID` | Service principal tenant (directory) ID. | |
| 216 | +| `AZURE_CLIENT_CERTIFICATE_PATH` | Path to a PEM or PKCS12 certificate file for certificate-based service principal auth. Used together with `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`. | |
| 217 | +| `AZURE_AUTHORITY_HOST` | Override the authority host for sovereign clouds (e.g., `login.microsoftonline.us`, `login.partner.microsoftonline.cn`, `login.microsoftonline.de`). Defaults to the commercial cloud. | |
| 218 | + |
| 219 | +For CLI-specific environment variables (config paths, debug logging, TE2 compatibility), see @te-cli-config. |
| 220 | + |
| 221 | +## Next steps |
| 222 | + |
| 223 | +- @te-cli-commands - what you can do once connected. |
| 224 | +- @te-cli-config - configuration and profile behavior. |
| 225 | +- @te-cli-cicd - pipeline examples using service principals and managed identity. |
0 commit comments