pac power-fx

(Preview) Commands for working with Power Fx

Use these commands to interact with data in Dataverse using a command line or script. Reduce the time and complexity of your Dataverse operations by using Power Fx.

You can use the formulas listed in the Formula reference - Power Platform CLI.

Commands

Command Description
pac power-fx repl (Preview) Launch interactive Power Fx Read-Eval-Print Loop
pac power-fx run (Preview) Run a file of Power Fx instructions

pac power-fx repl

(Preview) Launch interactive Power Fx Read-Eval-Print Loop

Optional Parameters for power-fx repl

--environment -env

Specifies the target Dataverse. The value may be a Guid or absolute https URL. When not specified, the active organization selected for the current auth profile will be used.

Remarks

This command provides a shell to use formulas listed in Formula reference - Power Platform CLI.

Start the Power Fx repl by running the following command:

pac power-fx repl

After that, you can run Power Fx commands.

Examples

The following examples show the use of the pac power-fx repl command.

Add rows
Collect(Contacts, { firstname: "Patti", lastname: "Fernandez" })

The Power Fx repl responds with the following:

{contactid:GUID("118d7b47-8f80-ee11-8179-0022482a40c7"), fullname:"Patti Fernandez", ...}
Help

Run the following command to get help about all the commands that are available in Power Fx repl:

Help()

The Power Fx repl responds with the following output:

  Abs             Acos            Acot            AddColumns      And
  Asin            AsType          Atan            Atan2           Average
  Blank           Boolean         Char            Clear           ClearCollect
  Coalesce        Collect         ColorFade       ColorValue      Concat
  Concatenate     Cos             Cot             Count           CountA
  CountIf         CountRows       Date            DateAdd         DateDiff
  DateTime        DateTimeValue   DateValue       Day             Dec2Hex
  Decimal         Degrees         Distinct        DropColumns     EDate
  EncodeUrl       EndsWith        EOMonth         Error           Exp
  Filter          Find            First           FirstN          Float
  ForAll          GUID            Help            Hex2Dec         Hour
  If              IfError         Index           Int             IsBlank
  IsBlankOrError  IsEmpty         IsError         IsMatch         IsNumeric
  IsToday         Language        Last            LastN           Left
  Len             Ln              Log             LookUp          Lower
  Match           MatchAll        Max             Mid             Min
  Minute          Mod             Month           Not             Notify
  Now             OptionSetInfo   Or              ParseJSON       Patch
  Pi              PlainText       Power           Proper          Radians
  Rand            RandBetween     Refresh         Remove          Replace
  RGBA            Right           Round           RoundDown       RoundUp
  Second          Sequence        Set             Shuffle         Sin
  Sort            Split           Sqrt            StartsWith      StdevP
  Substitute      Sum             Switch          Table           Tan
  Text            Time            TimeValue       TimeZoneOffset  Today
  Trim            TrimEnds        Trunc           Upper           Value
  VarP            Weekday         With            Year
>>

Note

These commands will change over time to include more commands. It should be synchronized with the documented currently available commands.

Exit

Use Exit() to exit the repl command.

pac power-fx run

(Preview) Run a file of Power Fx instructions

Examples

The following examples show the use of the pac power-fx run command.

Note

In each of these examples, you need to:

  1. Create a file named test-pfx.txt with Power Fx expressions in a folder on your computer, like c:\test.

  2. Open a Windows PowerShell window, navigate to the test folder and use the run command specifying the file that contains the commands: pac power-fx run --file test-pfx.txt.

To use Dataverse tables, you have to create and select an auth profile. See pac auth create and pac auth select.

If you get an error check Troubleshooting.

Create Dataverse records

  1. Add the following text to test-pfx.txt and save the file.

    Collect(Contacts, { firstname: "Megan", lastname: "Bowen" })
    Collect(Contacts, { firstname: "Garth", lastname: "Forth" })
    Collect(Contacts, { firstname: "Adele", lastname: "Vance" })
    Collect(Contacts, { firstname: "Patti", lastname: "Fernandez" })
    
  2. Run this command:

    PS C:\test> pac power-fx run --file test-pfx.txt
    

    You can expect output like the following:

    {contactid:GUID("80eb0c02-9180-ee11-8179-0022482a40c7"), fullname:"Megan Bowen", ...}
    {contactid:GUID("81eb0c02-9180-ee11-8179-0022482a40c7"), fullname:"Garth Forth", ...}
    {contactid:GUID("82eb0c02-9180-ee11-8179-0022482a40c7"), fullname:"Adele Vance", ...}
    {contactid:GUID("83eb0c02-9180-ee11-8179-0022482a40c7"), fullname:"Patti Fernandez", ...}
    

Query a Dataverse table

  1. Add this text to test-pfx.txt and save the file.

    FirstN(Contacts, 5)
    

    This command retrieves the first five contacts from Dataverse.

  2. Run this command:

    PS C:\test> pac power-fx run --file test-pfx.txt
    

    You can expect output like the following:

    Connected to... Your Organization
    Connected as you@yourorg.onmicrosoft.com
    
    contactid                                      fullname           ...
    ============================================== ================== =====
    GUID("eeb27495-d127-ed11-9db1-00224804f8e2")   Yvonne McKay (sample)
    GUID("cba0ed9e-d127-ed11-9db1-00224804f8e2")   Susanna Stubberod (sample)
    GUID("cea0ed9e-d127-ed11-9db1-00224804f8e2")   Nancy Anderson (sample)
    GUID("6cc7483c-7a77-ee11-8179-00224809f375")   Maria Campbell (sample)
    GUID("49b0be2e-d01c-ed11-b83e-000d3a572421")   Sidney Higa (sample)
    PS C:\test>
    

Use PowerFx functions

  1. Add the following text to test-pfx.txt and save the file.

    Set(x, 1)
    Result = If( Mid( "asdf",x,1 ) = "a", "X", "Y" )
    

    This example uses the Mid, If, and Set Power Fx functions.

  2. Run the following command:

    PS C:\test> pac power-fx run --file test-pfx.txt
    

    You can expect output like the following:

    PS C:\test> pac power-fx run --file test-pfx.txt
    x: 1
    true
    Result: "X"
    PS C:\test>
    
  3. Add the --echo parameter and you can expect this output:

    PS C:\test> pac power-fx run --file test-pfx.txt --echo
    Set(x, 1)
    
    x: 1
    true
    Result = If( Mid( "asdf",x,1 ) = "a", "X", "Y" )
    
    Result: "X"
    PS C:\test>
    

Required Parameters for power-fx run

--file -f

Path of file to execute

Optional Parameters for power-fx run

--echo -e

True if input commands should echo back to output

This parameter requires no value. It's a switch.

--environment -env

Specifies the target Dataverse. The value may be a Guid or absolute https URL. When not specified, the active organization selected for the current auth profile will be used.

Troubleshooting

The following are steps to troubleshoot errors you might encounter when using pac power-fx commands.

Error when no Dataverse authentication profile exists

You can get an error like this when you don't have a universal authentication profile associated with a Dataverse environment.

PS C:\test> pac power-fx run --file test-pfx.txt
Error 8-16: Name isn't valid. 'Contacts' isn't recognized.
Error 18-59: The specified column 'firstname' does not exist.
Error 0-60: The function 'Collect' has some invalid arguments.
Error 8-16: Name isn't valid. 'Contacts' isn't recognized.
Error 18-59: The specified column 'firstname' does not exist.
Error 0-60: The function 'Collect' has some invalid arguments.
Error 8-16: Name isn't valid. 'Contacts' isn't recognized.
Error 18-59: The specified column 'firstname' does not exist.
Error 0-60: The function 'Collect' has some invalid arguments.
Error 8-16: Name isn't valid. 'Contacts' isn't recognized.
Error 18-63: The specified column 'firstname' does not exist.
Error 0-64: The function 'Collect' has some invalid arguments.

To resolve errors like these, create a universal authentication profile associated with a Dataverse environment.

  1. Run the command pac auth list.

    You might see a result like the following that includes a UNIVERSAL authentication profile with no Url indicating it's associated with a Dataverse environment.

    Index Active Kind      Name Friendly Name Url User                Cloud  Type
    [1]   *      UNIVERSAL                        you@yourcompany.com Public OperatingSystem
    

    This isn't sufficient because no Dataverse environment is specified.

  2. Use pac auth create to create a UNIVERSAL authentication profile connected to a Dataverse environment.

    Note

    Use the --environment parameter using the environmentid value. Find your environment ID.

    Don't use the --url parameter because this will create a DATAVERSE profile rather than a UNIVERSAL profile.

    For example:

    PS C:\test> pac auth create --environment f2cef599-b112-4803-bb5d-090077017685 --name ConnectionName
    'you@yourcompany.onmicrosoft.com' authenticated successfully.
    Validating connection...
    Default organization: YourOrganization
    Connected to... YourOrganization
    Connected as you@yourcompany.onmicrosoft.com
    Authentication profile created
       * UNIVERSAL ConnectionName                 https://yourcompany.crm.dynamics.com/          : you@yourcompany.onmicrosoft.com              Public
    
    PS C:\test>
    
  3. Run pac auth list again. You should see a result with UNIVERSAL connection profile with a URL for your Dataverse environment.

    PS C:\test> pac auth list
    Index Active Kind      Name           Friendly Name        Url                                   User                  Cloud  Type
    [1]   *      UNIVERSAL                                                                           you@yourcompany.com   Public OperatingSystem
    [2]   *      UNIVERSAL ConnectionName YourOrganization     https://yourcompany.crm.dynamics.com/ you@yourcompany.com   Public User
    
    PS C:\test>
    
  4. Select the UNIVERSAL environment to make it the default profile using the pac auth select command.

    PS C:\test> pac auth select --index 2
    New default profile:
       * UNIVERSAL ConnectionName                 https://yourcompany.crm.dynamics.com/          : you@yourcompany.com              Public
    
    PS C:\test>
    

See also

Microsoft Power Platform CLI Command Groups
Microsoft Power Platform CLI overview