docs(cli): correct the relationship path form and drop the GUID claim - #392
Merged
gronnerup merged 1 commit intoSep 10, 2026
Merged
Conversation
The Containers and keywords section documented relationship paths as
Relationships/{guid}. Braces are reserved characters in CLI paths as of
0.7.0, so that form is refused by the path parser rather than resolved.
It also promised a GUID. The name is whatever the model carries: across
the checked-in .bim fixtures (52 distinct models, 3493 relationships) it
is an auto-generated label such as Relationship 1 in 55% of cases and a
GUID in 45%, mixed within single models.
Use Relationships/<name> and describe the name instead. Quoting is left
to the Quoting section, which already covers reserved characters.
Work item 7269.
gronnerup
approved these changes
Sep 10, 2026
jeroenterheerdt
pushed a commit
that referenced
this pull request
Sep 11, 2026
* docs(cli): remove the load, open, and replace commands
These three commands were removed from the CLI during Limited Public
Preview, so the docs should carry no trace of them:
- `replace` (PR !4065) - unguarded model-wide string replacement that
could corrupt names or expressions merely sharing a substring
- `load` (PR !4066) - superseded by `te get .` and `te ls Tables`
- `open` (PR !4071) - Windows-only TE3 Desktop launcher
Removed the three command-reference sections and every mention across the
CLI docs. Two spots needed rewriting rather than deletion:
- `te find` documented its `--in <scope>` values as "as per `te replace`";
the scope list is now inlined so the entry stands on its own. Verified
against FindCommand.cs, whose option description is the identical string,
and FindReplaceUtils.ParseScope, which accepts exactly those tokens.
- The `te replace` dry-run tip in te-cli-automation is now a general note
on what mutating commands do without `--save`. Verified against
AddCommand, SetCommand, MvCommand, RmCommand, FormatCommand,
ScriptCommand and MacroCommand, which all emit "Changes not saved. Use
--save to persist.", and RmCommand's --dry-run ("Show what would be
removed without doing it").
The `open` removal also deleted the `te3ExePath` config key and the
`TE3_EXE_PATH` environment variable from CliConfig.cs and ConfigCommand.cs,
so both are dropped from the config schema, the File paths table, and the
environment variables table.
English source only. The es and zh translations under localizedContent/
still reference these commands and are handled separately, either by the
localization pipeline or in a follow-up.
No release-note entry: the CLI is still in preview, so these commands were
never generally available.
* docs(cli): post-cherry-pick fix-ups for the removed-commands note
te format no longer exists, and the dry-run trailer printed by the
standard mutating commands is "Dry run - nothing saved. Add --save to
persist."
* docs(cli): preview end date is 2026-10-31
* docs(cli): rewrite the command reference for the 0.7.0 surface
Every command and example now matches the CLI's own help output:
- format and incremental-refresh sections removed; formatting lives in
te set --format and the new te util namespace, refresh policies are
plain RefreshPolicy properties under te set plus te refresh
--apply-refresh-policy
- save is documented under its canonical name save-as
- property assignments are -p Name=Value everywhere; the -q/-i pairs
are gone from set, add, macro set and bpa rules set
- the model is always resolved from --model/-s -d/--local/--recent or
the active connection, never a positional path
- deploy and refresh are dry runs by default: --execute acts,
--target-server/--target-database name the deploy destination,
remote-to-remote deploys documented
- script sources are --file/--inline with --validate as the
model-free compile check
- get documents the full read pipeline (--where, --ls, --deps,
--unused, --paths-only); list gains kpi/set/function types and the
KPIs/Sets container keywords; reserved path characters documented
- shared model-editing note covers the dry-run default, the
--diff/--stat/--name-only trio and the mutationOutput config key
- bpa run reflects the built-in rule set matching TE3 Desktop and the
per-layer duplicate-ID resolution
- test run documents suite pre-validation and the unified findings
JSON; validate/bpa run/query cross-reference the findings page
- te init defaults to compatibility level 1705 and is idempotent
* docs(cli): new Findings JSON page for the unified envelope
Documents the shared JSON shape emitted by te validate, te bpa run,
te test run and te query under --output-format json: the envelope,
the per-finding key contract (including which sources populate
objectPath and expressionPosition, both optional), the closed
objectType vocabulary, per-command extras, and the shared CI
annotation behavior. Registered in the CLI toc block.
* docs(cli): interactive and configuration pages for 0.7.0
Interactive: examples use --model (no positional model), get projects
with -p, deploy examples carry --execute, and the page now covers the
REPL's staged-edit model (save/revert builtins, --save/--stage/--revert,
interactiveEditMode), line editing and keys, and the stdin '-'
convention being unavailable inside the session.
Config: the format-options intro reflects where each layout key and
useSqlBiDaxFormatter actually apply (autoFormat always uses the
built-in formatter), the autoFormat row describes mutation-scoped
formatting, the new mutationOutput key is documented in the schema and
defaults table, save is named save-as, bpa run examples use --model,
profile-overridable keys are listed, and te remove joins the
bpa.onMutation gate list.
* docs(cli): auth and automation pages for 0.7.0
Every deploy example uses --model for the source,
--target-server/--target-database for the destination, and --execute
(deploy and refresh are dry-run by default). Query examples parse the
JSON envelope (rows lives under .rows), the Python stderr parser gets
--error-format json, and the refresh TMSL idiom redirects the default
dry-run output instead of the removed --dry-run flag.
te connect --local now describes every local Analysis Services
instance with the two-step instance/database prompt. New coverage:
Entra ID sign-in for schema detection against Azure-family SQL
endpoints, the active connection doubling as the default deploy
target, the stdin '-' convention, the mutation change-output trio and
mutationOutput key, notices on stderr, and a cross-reference to the
findings JSON page.
* docs(cli): CI/CD and limitations pages for 0.7.0
CI/CD: both workflow examples use --model for the source and
--target-server/--target-database plus --execute on deploy; refresh
patterns carry --execute (dry run is the default); artifact patterns
redirect the default dry-run TMSL; the CI-friendly list leads with the
dry-run default and the unified findings JSON; structured errors are
--error-format json; new script compile-check pattern.
Limitations: the schema-drift row is gone (te set --update-schema
covers it); the Model I/O row names save-as and --supporting-files;
BPA duplicate-rule-ID resolution documented; new rows for reserved
path characters and cmd.exe, stdin '-' inside the REPL, set objects
being inspect-only for add/remove/move, no whole-model M sweep, and
schema-sync rename semantics.
* docs(cli): migration and AI-skill pages for 0.7.0
Migrate: the mapping reference is te util migrate; the file row maps
to the global --model option (no positional model anywhere); script
maps to --file/--inline; save rows use te save-as with the format
inferred from the output path; deploy maps to
--target-server/--target-database plus --execute; -X/-XMLA maps to
redirecting the default dry-run TMSL; the playbook and differences
sections reflect the dry-run default.
Skill: the skill is a folder (SKILL.md plus references/), so the
download, install, zip, AGENTS.md, and update steps all carry the
references/ subfolder; the coverage list names save-as and util; the
staging bullet reflects dry-run by default; the smoke test asks about
deploy without --execute; the dangling Copilot custom-instructions
references are gone.
* docs(cli): overview and install pages for 0.7.0
The overview's family table names te save-as and te util, the
Deployment & Refresh family describes applying refresh policies, and
the Configuration family describes CLI settings. A fourth design
pillar states the safe-by-default execution model (preview until
--save, TMSL until --execute). The install feature matrix drops the
device-code auth method and describes local model-file support without
command vocabulary.
* docs(cli): verification sweep fixes on the TE2 comparison table
The TE2-vs-te comparison rows now match 0.7.0: script emission is the
deploy dry-run default (no --xmla), te script compile checks with
--validate, formatting lives in te set --format and te util, te diff
exits 1 on differences and 2 on comparison errors, refresh is dry-run
by default with --execute, and the interactive shell is described by
its persistent history and staged edits.
* Update CLI screenshots
* Update te-cli-migrate docs
* docs(cli): correct the relationship path form and drop the GUID claim (#392)
The Containers and keywords section documented relationship paths as
Relationships/{guid}. Braces are reserved characters in CLI paths as of
0.7.0, so that form is refused by the path parser rather than resolved.
It also promised a GUID. The name is whatever the model carries: across
the checked-in .bim fixtures (52 distinct models, 3493 relationships) it
is an auto-generated label such as Relationship 1 in 55% of cases and a
GUID in 45%, mixed within single models.
Use Relationships/<name> and describe the name instead. Quoting is left
to the Quoting section, which already covers reserved characters.
Work item 7269.
* Final update of docs based on latest 0.7.0 release
* docs(cli): refresh CLI pages for 0.7.0 release notes since 2026-09-04
Covers the notes merged to release/tecli/0.7.0 since the last sweep plus
the pending #7324 (te get --properties) and #7266 (--semicolons dialect)
changes: --unset and null clearing, schema-source inference and
--data-source, te get wildcard listing and objectPath, te find literal
matching, te diff change shape, refresh --execute confirmation and --force,
deploy failing on server object errors, te script exit code, validation
codes TE0012-TE0014, --ci aliases, useSemicolons config key removal,
administrator policies, and interactive-shell exit safeguards.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* Changes bsed on first round of review on the 0.7.0 docs
---------
Co-authored-by: Maria Jose Ferreira Fernandes <171664470+MariaJoseFF@users.noreply.github.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes work item 7269. Replaces #391 (closed).
Targets
user-pg/cli-0.7.0, the branch behind #386, so this does not reachmainbefore the CLI 0.7.0 ships.One line in
content/features/te-cli/te-cli-commands.md, in Containers and keywords:Two defects, both fixed by that line
1. The documented path was unparseable.
{and}became reserved characters in 0.7.0 ([Breaking] Braces asterisks and question marks in object names must be quoted in paths), so the documented form is refused rather than resolved:Two rules in the same release contradicted each other.
<name>matches the placeholder convention used everywhere else in that sentence and collides with nothing.2. It promised a GUID. The name is whatever the model carries. Census of every checked-in
.bimfixture, deduplicated by content hash, 52 distinct models / 3493 relationships:Relationship NNew Single Column Relationship NThe shapes are also not split by source:
AdventureWorks.bimand three other fixtures mix GUID andRelationship Ninside one model, andTOMWrapperTest/TestData/TMDL-SSAS-Model/relationships.tmdl, an SSAS-sourced model, is entirely bare GUIDs.Verified against te 0.7.0.3, one model per shape. All three round-trip into
te getunchanged:--paths-onlyprints6f6e1b0a-1c2d-4e3f-9a8b-7c6d5e4f3a2bRelationships/6f6e1b0a-1c2d-4e3f-9a8b-7c6d5e4f3a2b{2c4f8a19-1c2d-4e3f-9a8b-7c6d5e4f3a2b}Relationships/"{2c4f8a19-1c2d-4e3f-9a8b-7c6d5e4f3a2b}"Relationship 1Relationships/Relationship 1Quoting tracks whether the name contains a reserved character, not the object type, so it belongs in the Quoting section (line 51) that already owns that rule rather than in this clause.
Follow-ups, deliberately not in this PR
Relationships/{guid}also appears three times in the TE3 repo release notes onrelease/tecli/0.7.0. Separate repo, separate PR.'Relationships/"{guid}"'works only on PowerShell 7.3+ withStandardnative argument passing, and fails underLegacy. The bracket form"Relationships/[{guid}]"works in every shell tested.'{foo}'first, which can never work in a non-table container; andte addsilently created a second active relationship on an endpoint pair that already had one, giving two indistinguishable rows inte list.