CLI Docs 0.7.0 - #386
Open
gronnerup wants to merge 12 commits into
Open
Conversation
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.
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."
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
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.
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.
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.
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.
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.
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.
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.
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-386.westeurope.azurestaticapps.net |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-386.westeurope.azurestaticapps.net |
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.
Full overhaul of the te CLI documentation so every page describes the current CLI, covering everything that landed since the last CLI release. The current version is the only truth on the docs site: no removed functionality is mentioned anywhere, and breaking-change history stays in the release notes.
Branch incorporation. Cherry-picked
docs(cli): remove the load, open, and replace commandsfromuser-mjf/docs-cli-remove-load-open-replace(clean, no conflicts), plus two follow-up fixes the commit predates (te formatin the mutating-command list, the current dry-run trailer wording). Theuser-mjf/docs-te-cli-interactive-piped-stdinbranch was not merged: its content already reached main via #355/#356, so it can be deleted.Highlights
te-cli-commands.mdrewritten for the current surface:load/open/replace/format/incremental-refreshsections gone,save-asas the canonical name,-p Name=Valueproperty syntax,--model-based model resolution (no positional model anywhere), dry-run-by-defaultdeploy/refreshwith--executeand--target-server/--target-database, thegetread pipeline (--where/--ls/--deps/--unused), KPIs/Sets containers and the reserved-character quoting rules, a new Utilities section (util format-dax/format-m/migrate), and a shared model-editing note for the dry-run default and the--diff/--stat/--name-onlyoutput trio.te-cli-findings.mddocumenting the unified findings JSON envelope shared byvalidate,bpa run,test run, andquery, registered in the toc.mutationOutput, corrected formatter scoping), auth/automation (envelope-aware Python/PowerShell examples, stdin-patterns), CI/CD (both workflow examples now actually deploy: they previously exited 0 without deploying), limitations, migrate (te util migrateand re-mapped flag rows), AI skill (folder framing withreferences/), overview/install, and the TE2 comparison table onCommand-line-Options.md.Verification. Every example was checked against the CLI's own
--helpoutput from a fresh build of TE3 main. Dead-term sweeps over the content (removed commands, dead flags,-q/-isyntax, positional model paths, old preview date) come back clean; all cross-page anchors resolve after the commands-page restructure; DocFX builds with 0 errors (the one warning,content/index.htmlvsindex.md, is pre-existing).Deliberately not changed. The migrate page keeps TE2's
-SC/-SCHEMACHECKas not implemented, matching the livete util migrateoutput. Out of scope, tracked separately: the te-cli AI skill content in the CLI repo (heavily stale for the current CLI), localized es/zh content (localization pipeline), and deleting the obsoleteuser-mjf/docs-te-cli-interactive-piped-stdinbranch.