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 six current commands, each designed for specific operational needs:

Command	What it does	Connects to Dataverse?
translate	Translates a solution customizations.xml, or a whole solution zip including its PCF control strings	No. File in, file out
organizationsetup	Copies reference data from a master data environment into a target	Yes
datamanipulation	Repairs and maintains existing data after a release	Yes
extract	Extracts one table to CSV over the read-only TDS endpoint	Yes — as you, never a service principal
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 data management operations to update existing records after feature implementations or migrations. This includes rebuilding activity relationships, updating email data, managing family groups and handling referrals. Table extraction moved to the extract verb.

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.

It takes either of two inputs:

Input	What is translated	Output
customizations.xml (the default)	Every English (1033) label and description	customizations-translated.xml, or the path given with --OutputFile
A solution .zip	The same labels in the zip's customizations.xml, plus the English strings of every PCF control in the zip	{name}-translated.zip beside the input, or the .zip path given with --OutputFile

WhanauTahi.Xpm.Tooling.CLI.exe translate --InputFile WhanauTahiComponents.zip --OutputFile WhanauTahiComponents_en-us.zip --Languages en-us

A PCF control keeps its on-screen text in string files named by language: {name}.1033.resx for English, {name}.1036.resx for French, and so on. The control reads the file for the user's language when it runs, so translating the copy inside the solution zip is what changes the words on screen. Only English files are translated, the same rule customizations.xml follows. Within them only the text of each string changes. The keys the control looks up by, the notes left for translators, and the files for other languages stay exactly as they are. A changed string is written into the file in place of the old one, so everything else in the file, down to its formatting, stays as it was. A string that holds anything but text, such as a comment, is left as it is. A string file with nothing to translate comes out byte for byte the same, and every other file in the zip is copied across unchanged.

Text that a control has written into its code, rather than into a string file, is not translated.

--Languages takes one or more language keys separated by commas, applied in the order given. A key the tool does not recognise changes nothing. A zip that cannot be read, an output that cannot be written, or an English string file that cannot be read as XML or is not UTF-8, stops the run with exit code 1, and nothing is written. The tool does not convert a file: the message names the file and its encoding, so re-save it as UTF-8 and run again. PCF tooling writes string files as UTF-8, so this should only happen to a file edited by hand. The files for other languages, and those of a control named in --SkipControls, are copied across without being read, so they are not checked.

Skipping a control that localises itself

Some controls choose their own words when they run. EnrolmentActivities reads the environment's country setting and shows te reo Māori in New Zealand and plain English everywhere else, both from its own string file. Translating that file as well does the job a second time. The language map rewrites words the control had already chosen for its reader, and its sentences no longer read as they were written.

--SkipControls leaves a control like this alone. It takes one or more control names separated by commas. Every string file of a named control is copied across byte for byte, and the rest of the zip is translated as usual. The run's summary names each control it skipped.

WhanauTahi.Xpm.Tooling.CLI.exe translate --InputFile WhanauTahiComponents.zip --Languages maori --SkipControls WTL.PCF.EnrolmentActivities

A control is named by its folder under Controls/ in the zip. That folder is the publisher prefix, an underscore, then the control's namespace and constructor: mag_WTL.PCF.EnrolmentActivities. Give the name whole or without the prefix, in any case, so WTL.PCF.EnrolmentActivities and mag_wtl.pcf.enrolmentactivities both work. Part of a name, such as EnrolmentActivities on its own, does not. A name without its prefix must pick out one control. If a zip holds mag_WTL.PCF.Grid and wt_WTL.PCF.Grid, WTL.PCF.Grid stops the run with exit code 1, listing both, and nothing is written. Give the whole folder name of the one to skip. A whole folder name always picks out that folder alone.

A name that matches no control in the zip stops the run with exit code 1, and nothing is written. The error lists the controls the zip does hold. Without this check a misspelt name would translate the very control it was meant to protect, and nothing in the output would show it. For the same reason an empty --SkipControls is refused, and so is --SkipControls with a customizations.xml input, which has no controls to skip.

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.

View print documentation →

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.
extract	No client id or secret — there are no such options. It reads the TDS endpoint as you, from your az login session or, with --Interactive, a browser. With no usable identity the run is refused with exit code 3.
organizationsetup, datamanipulation, 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 a run was refused before anything was attempted — assessmenttransfer's apply confirmation being declined, or datamanipulation being asked to write without --Apply or to preview an operation that has no preview.

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:

1. Request the Navigator Platform CLI files from Whānau Tahi support.

or

2. If you have access to the Whānau Tahi Devops project, download the artifact from the latest WhanauTahi.Xpm.Tooling Devops 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.