What is Navigator Platform CLI?
Whānau Tahi Navigator Platform CLI is a powerful command-line tool that empowers developers and administrators to perform essential operations in Navigator Power Platform environments. The CLI streamlines common tasks related to application lifecycle management, environment setup, data management, solution deployment, and customisation.
The Navigator Platform CLI is intended to be used only by developers or advanced administrators who are trained in the use and customisation of Power Platform and Dataverse model-driven apps.
Available Commands
The CLI ships five current commands, each designed for specific operational needs:
| Command | What it does | Connects to Dataverse? |
|---|---|---|
translate |
Translates a solution customizations.xml into other languages |
No — file in, file out |
organizationsetup |
Copies reference data from a master data environment into a target | Yes |
datamanipulation |
Repairs and maintains existing data; extracts tables via TDS | Yes, except --ExtractTable |
print |
Generates PDF documents from Dataverse records | Yes, in every mode |
assessmenttransfer |
Moves one Dynamic Assessment's configuration between environments | Yes |
Three further commands — solution, crmenvsetup and assessmentprep — are still in the tool but are
deprecated. They are described under Legacy Commands.
The CLI does not pack or unpack solution files. Packing, unpacking, exporting and importing solutions are Microsoft Power Platform CLI (PAC) operations.
datamanipulation - Manage Existing Data
Provides powerful data management operations to update existing records after feature implementations or migrations. This includes rebuilding activity relationships, updating email data, managing family groups, handling referrals, and extracting data via TDS endpoints.
Use this when: You need to update existing data to align with newly deployed features, fix data inconsistencies, or extract large datasets for analysis.
View datamanipulation documentation →
organizationsetup - Deploy Reference Data
Copies reference data and configuration from a master data environment to target environments. This includes outcomes frameworks, service configurations, contracts, assessment tools, and supporting reference tables. Supports full environment setup or targeted dataset synchronisation.
Use this when: You need to establish consistent reference data across development, test, and production environments, or synchronise configuration changes between environments.
View organizationsetup documentation →
translate - Localise Solutions
Translates Navigator solution customisation files (customizations.xml) into multiple languages. This command processes solution metadata and generates translated versions for multi-language deployments.
Use this when: You need to prepare solution packages for deployment in regions requiring localised language support.
print - Generate PDF Documents
Generates PDF documents from Dataverse records, supporting both single record exports and comprehensive plan-mode exports that aggregate related data across individuals, referrals, and activities. This command processes form configurations, field data, dynamic assessments, and images to produce formatted PDF outputs.
Use this when: You need to generate printable PDF reports from Navigator records, export comprehensive plans with related data, or automate document generation as part of backend workflows.
Every print mode connects to the environment first, including --test, which exists to prove that connection works.
assessmenttransfer - Move a Dynamic Assessment Between Environments
Copies one named Dynamic Assessment's configuration — the assessment, its published version, and everything that version needs to render — from a source environment into a target environment. The source is only ever read. Runs are a dry run by default and print the full change set before anything is written.
Use this when: You have built or amended a Dynamic Assessment in one environment and need the same assessment, recognisable as the same assessment, in another.
View assessmenttransfer documentation →
Authentication
The CLI carries no application registration and no secret of its own. The service principal belongs to the tenant being worked on, and is passed in on every run.
| Command | What it needs |
|---|---|
translate |
Nothing. It never opens a connection. |
datamanipulation --ExtractTable |
Nothing on the command line: the TDS extraction path authenticates against the TDS endpoint itself. |
organizationsetup, datamanipulation (all other operations), print, and the legacy solution, crmenvsetup and assessmentprep |
Both --ClientId and --Secret. Whānau Tahi staff working by hand have one alternative — see Interactive sign-in. |
assessmenttransfer |
An authConfig.json holding applicationId and clientSecret, found via --AuthConfig. |
A connected run started without both values is refused with exit code 3. Nothing is attempted and no
environment is contacted; the message names which value was missing. Exit code 1 still means a usage
error or a failed run, and exit code 2 means the operator declined assessmenttransfer's apply confirmation.
In a pipeline, supply both from pipeline variables backed by Key Vault. Never commit a secret, and never paste one into a shared script.
Interactive sign-in (Whānau Tahi internal use)
The six connected commands above — organizationsetup, datamanipulation, print, and the legacy
solution, crmenvsetup and assessmentprep — have one more way to connect. When --ClientId and
--Secret are not supplied and a person is at the keyboard, the run signs in interactively by
device code: it prints a URL and a short code, waits while that code is approved in a browser, and then
carries on against the environment named by the command's own URL option. The approved token is cached
on the machine, so later runs sign in silently.
Important
Interactive device-code sign-in is for Whānau Tahi internal use. Customers supply --ClientId and
--Secret: they belong to the customer's own tenant, and are the only supported way for a customer to
run these commands.
Nothing about the fail-closed contract changes for anyone else:
| Situation | What happens |
|---|---|
--ClientId and --Secret both given |
Connects with that service principal. Unchanged, and what pipelines and customers do. |
| Either missing, person at the keyboard | Signs in interactively by device code, after saying so on stderr. |
| Either missing, unattended but with a console (cron with a tty, scheduled task) | Treated as a person: the run blocks on the sign-in prompt until the code expires (~15 minutes). Set CI=1 (or any build-agent variable) so unattended scripts fail fast with exit 3 instead. |
| Either missing, no person — a pipeline, a redirected shell, a build agent | Refused with exit code 3. Nothing is attempted. |
"No person" is decided by the console and the environment: input redirected into the tool, or any of
CI, TF_BUILD or GITHUB_ACTIONS set, means nobody is there to approve a sign-in. A pipeline that
loses its secret therefore fails as it always has, rather than hanging on a prompt no one will answer.
The identity used for interactive sign-in is set with the NAVIGATOR_PUBLIC_CLIENT_ID environment
variable, and falls back to the shared first-party Dataverse tooling application when it is unset.
translate and assessmenttransfer are unaffected: translate never connects, and
assessmenttransfer keeps its own --AuthConfig contract.
Legacy Commands
assessmentprep - Create New Assessment Tools
Automates the creation of new assessment tool entities in Navigator environments. This command creates the entity structure, fields, forms, and relationships required for a custom assessment tool to integrate seamlessly with Navigator's assessment framework.
Important
This set of commands has been deprecated. Please use Dynamic Assessments instead.
If you have not had an upgrade to receive the Dynamic Assessment capability, please get in touch with us at support@whanautahi.com.
You can read more details about the feature here: Dynamic Assessments Release Notes
View assessmentprep documentation →
crmenvsetup - Configure Power Platform Environments
Sets up newly created Power Platform environments with required security roles and permissions. This command ensures that key users have the necessary system administrator access to begin configuring the environment.
Important
This set of commands has been deprecated.
solution - Deploy Solutions
Imports, stages and upgrades a solution file that has already been built, and reports on the resulting job. It does not pack or unpack solutions.
Important
This set of commands has been deprecated. Please use Microsoft's PAC CLI instead, which you can download from Microsoft Power Platform CLI.
Install Whānau Tahi Navigator Platform CLI
You can use te following ways to install Whānau Tahi Navigator Platform CLI:
- Request the Navigator Platform CLI files from Whānau Tahi support.
or
- If you have access to the Whānau Tahi Devops project, download the artifact from the latest
WhanauTahi.Xpm.ToolingDevops pipeline.
When you have obtained the files, copy them to a location on your local hard drive (e.g. C:\WhanauTahi.Xpm.Tooling).
You may also need to add a folder exception to your anti-virus software to allow the application to run.
Note
- Currently, Whānau Tahi Navigator Platform CLI is supported only on Windows 10 and Windows 11.
- You must have the Microsoft .NET 10 runtime installed to use Navigator Platform CLI.