Connect¶

Commands for working with connections and deployed models. The connection model itself — sessions, profiles, workspace mode — is explained in Connections & sessions.

connect — set the active connection¶

tx connect [server] [database] [options]

No arguments shows the current connection and the session that holds it. For a Power BI Desktop session it shows the report name, and flags the session as (not running) — with the last-known report — once that Desktop window has been closed. The first argument can be a workspace name, an endpoint, or a local model path.

tx connect                          # show current
tx connect --remote
tx connect MyWorkspace Sales
tx connect ./model.tmdl
tx connect --local                  # Power BI Desktop (Windows only)
tx connect MyWorkspace --list       # models on a workspace, no connect
tx connect --local --list           # running Desktop instances, no connect
tx connect localhost:56164          # a specific Desktop instance from the list
tx connect ./model.tmdl -w MyWorkspace Sales
tx connect --clear --all             # forget the connection everywhere

A workspace that hosts more than one model cannot be opened without naming one: commands such as tx ls -s MyWorkspace fail with TOMIX_DATABASE_REQUIRED. List the models first, then pass one with -d:

tx connect MyWorkspace --list --output-format json
tx ls -s MyWorkspace -d Sales

With --output-format json the listing is {"server": "<endpoint>", "models": [{"name", "compatibilityLevel", "lastUpdate"}]} inside the standard envelope; compatibilityLevel and lastUpdate are null when the server does not report them.

deploy — deploy to a workspace¶

tx deploy [model] [options]

Runs the BPA gate before deploying. The gate blocks only on findings at or above the severity threshold: error-severity by default, or warnings too with --bpa-fail-on warning. A rule that cannot be evaluated is itself an error-severity finding — a broken rule expression blocks the deploy (named in the message) instead of silently skipping the rule. The built-in statistics rules are in the default-off vertipaq preset; the gate adds it to standard when the model has Vertipaq_* annotations, so a model annotated with tx vertipaq --annotate --save is checked for referential-integrity and size problems. When a rule from bpa.rules, TOMIX_BPA_RULES, or --bpa-rules needs VertiPaq statistics the model doesn't have, it is not checked. The deploy still proceeds, with a TOMIX_BPA_VERTIPAQ_STATS_MISSING warning that names them and says how to collect the statistics: tx vertipaq --annotate --save on a deployed model, or on a local model connected to one in workspace mode. Besides the built-in standard ruleset, the gate loads the rule files that the bpa.rules config key and the TOMIX_BPA_RULES environment variable name, then --bpa-rules; a later source overrides an earlier one for the same rule ID (see rule sources). Set TOMIX_BPA_RULES in a pipeline to gate every deploy on the team's rules. The gate honors bpa rules ignore --user: it skips any rule you ignore locally when that rule is among the gate's loaded rules. bpa run also loads your config-dir bpa-rules.json and the model's rules, so the commands may report different findings.

Without -s/--server, the target comes from the active connection: a remote connection deploys to itself, and a local connection with a workspace-mode mirror deploys to the mirror.

deploy previews first. It shows what the deploy would change on the target (+ = added to the target, - = removed from it), then asks before deploying. The preview compares the target against the exact model this deploy would leave behind, so anything granular deployment preserves is not reported as a change, and a target that does not exist yet is reported as "will be created". Where it cannot prompt (--non-interactive, --quiet, JSON output, or redirected input), it stops after the preview and exits 3. Pass --yes to deploy without the preview. --xmla only writes a script, so it neither previews nor asks.

After a deploy runs, deploy re-reads the deployed model and checks the state the server reports for each object — the server accepts a model whose DAX does not resolve, so "deployed" alone is not proof it works. Measures, columns, partitions, calculation items, format-string and detail-rows expressions, hierarchies, relationships, RLS table permissions, and functions are checked:

If the deployed model cannot be re-read, the deploy still succeeds with a TOMIX_DEPLOY_VALIDATION_UNAVAILABLE warning. With --ci, errors and warnings become CI annotations. JSON output adds a validation object to data (omitted on previews and --xmla):

"validation": {
  "issues": [
    {"severity": "Error", "objectType": "Measure", "objectName": "Sales[Total]",
     "state": "SemanticError", "message": "..."}
  ],
  "errors": 1, "warnings": 0, "unprocessed": 0
}

The preview diff ignores engine-derived calculated-table column data types, including type differences when a column exists on both the processed target and the planned model. Other column property changes remain visible.

tx deploy ./model.tmdl                          # preview, then confirm
tx deploy ./model.tmdl --profile prod --yes     # deploy without the preview (CI)
tx deploy --server MyWorkspace --database Sales
tx deploy ./model.bim --xmla deploy.xmla
tx deploy ./model.tmdl --bpa-fail-on warning

Rolling back a broken deploy¶

Without --rollback-on-error, the check above runs after the deploy has committed, so a model with errors is already live on the target when deploy reports it. With --rollback-on-error, the check runs before the change is kept, and a deploy with an error never reaches the target:

• Existing model. The deploy runs inside a server transaction. It applies the same merged model as an ordinary deploy, including everything granular deployment preserves. While the transaction is open, the server already reports the state of the uncommitted objects. If an object is in an error state, the transaction rolls back and the target keeps its previous definition and data. Otherwise it commits.
• New model. The server cannot create a database inside a transaction. The deploy creates the model and checks it, and if an object is in an error state it deletes the model again.

A rolled-back deploy fails with TOMIX_DEPLOY_ROLLED_BACK (exit 1), lists the broken objects, and reports "status": "rolled-back" in JSON. A check that cannot read the model also rolls back, because nothing proves the model works. Warnings (incomplete objects) and unprocessed objects do not roll back. The flag cannot change a model's compatibility level, because that change commits on its own; deploy once without the flag to upgrade the level. --rollback-on-error cannot be combined with --xmla.

tx deploy ./model.tmdl --profile prod --yes --rollback-on-error

Granular deployment¶

When the target model already exists, deploy preserves everything the target owns by default: partitions (including processed incremental-refresh data), data source connection strings, shared expressions (M parameters), roles, and role members. Only the model structure — tables, columns, measures, relationships — is overwritten. Each aspect can be opted into deployment individually:

Preservation only applies to an existing target; the first deploy of a model always ships the full source. --xmla reads the target when any aspect is preserved so the generated script matches what a real deploy would execute — use --deploy-full to generate a script offline. Generated scripts never contain credentials: only a direct deploy carries restricted connection-string information. On targets with dataSource objects (Azure AS, SSAS — Power BI and Fabric models keep connections in M instead), this means an --xmla script is not equivalent to a direct deploy: createOrReplace replaces each data source with the credential-stripped copy in the script, so executing it disconnects those data sources until credentials are re-entered on the server. Prefer a direct deploy when data sources are in play; treat --xmla output as a preview or an audit artifact there, not a deployment vehicle.

tx deploy ./model.tmdl                                   # promote structure, keep target data and config
tx deploy ./model.tmdl --deploy-roles                    # also push RLS definitions, keep members
tx deploy ./model.tmdl --deploy-partitions               # push partitions, keep incremental-refresh data
tx deploy ./model.tmdl --deploy-full                     # overwrite everything (first-deploy semantics)

tx deploy ./model.tmdl --xmla preview.xmla

refresh — trigger a data refresh¶

tx refresh [options]

tx refresh --refresh-type full
tx refresh --table Sales --table Customers
tx refresh --model "Sales.SemanticModel" --table Sales   # the PBIP open in Power BI Desktop

Files cannot be refreshed, so the target is a deployed model: the connection's server, or its workspace-mode secondary. When the model is a PBIP's files (the .pbip, its .SemanticModel folder, or anything in it) and no remote target is set, refresh runs in the Power BI Desktop that has that PBIP open, and says so. Save in Desktop to keep the data. Desktop is found from the file it was started with, so a project opened from Desktop's File menu is not matched: pass --server localhost:<port> (tx connect --local --list shows it) instead.

While it runs, a live panel shows the elapsed time, how many tables are done and in progress, and the rows loaded so far, then one line per in-progress table — oldest first, capped at six — with its current step (querying, reading, compressing, hierarchies, calculated columns), the partition for multi-partition tables, its rows, and how long it has been running. Once no table is in progress it shows the model-level step (relationships, calculation script, commit). The summary lists each table with Rows, Query (source query), Read, Process (post-load hierarchies and calculated columns), and Total, with a sub-row per partition when a table has several, followed by a phase table (data load, hierarchies, calculated columns, relationships, calculation script, commit) in wall-clock time. With --output-format json the same detail is in tables[].processMs, tables[].partitions, and phases; the CSV columns are unchanged. Power BI / Fabric delivers the trace a few seconds behind the refresh, so the summary can appear a little after the refresh itself finishes; the reported duration is the refresh's own.

Routine refreshes run straight away. The partition-risky variants preview first: --refresh-type clearvalues (wipes partition data), --skip-refresh-policy / --apply-refresh-policy false (refreshes all historical partitions), --policy-only, and --effective-date (shifts policy window boundaries). They print the TMSL the refresh would send (a validated operation summary for --policy-only), then ask before refreshing, on the same connection. Where they cannot prompt (--non-interactive, --quiet, JSON output, or redirected input), they stop after the preview and exit 3. Pass --yes to run them without the preview.

Apply a saved policy with data loading, or bootstrap empty partitions:

tx refresh --table Sales --apply-refresh-policy true -s MyWorkspace -d MyModel
tx refresh --table Sales --policy-only -s MyWorkspace -d MyModel          # preview, then confirm
tx refresh --table Sales --policy-only -s MyWorkspace -d MyModel --yes

--policy-only uses the deployed policy; it does not deploy local edits. It accepts --effective-date and positive --max-parallelism. It cannot be combined with --partition, an explicit --refresh-type, --trace, or disabling policy application. Its preview verifies the target table and policy without applying it; exact partition changes are determined by the server during execution. JSON execution results include policyApplication (operations, date, and refreshed: false); previews include policyPreview. Ordinary refresh output remains unchanged.

After an empty policy-only bootstrap, a normal policy refresh loads the incremental window; historical partitions can remain empty. To backfill all existing partition ranges without moving the policy window, use:

tx refresh --table Sales --refresh-type full --skip-refresh-policy -s MyWorkspace -d MyModel --yes

save — export a model¶

tx save [model] [options]

tx save -s MyWorkspace -d Sales -o ./sales.tmdl          # download a deployed model
tx save ./model.tmdl --serialization bim -o ./model.bim  # convert formats

auth — authentication¶

tx auth <login|logout|status>

auth login options:

tx auth login                          # interactive browser login
tx auth login --device-code            # no local browser (SSH, containers)

# Service principal — secret from stdin (CI) or a file, never argv
printf '%s' "$SECRET" | tx auth login -u $APP_ID --tenant $TENANT --password -
tx auth login -u $APP_ID --tenant $TENANT --password-file ./secret.txt

tx auth status
tx auth logout