pac copilot

Tools and utilities for copilot management.

The init, clone, pull, push, and pack commands let you keep a Copilot Studio agent as a set of files on disk, edit it locally, and synchronize it with a Dataverse environment.

A typical loop looks like this:

1. Start a workspace. Scaffold a brand-new agent with pac copilot init, or download an existing one with pac copilot clone. Either way you get a local workspace that carries the sync metadata the other commands depend on.
2. Pull before you edit. pac copilot pull brings remote changes down and merges them into your local files, so you start from the current server state.
3. Push when you're done. pac copilot push sends your local changes back. If the same item changed on the server in the meantime, push stops and asks you to pull first.
4. Package for deployment. pac copilot pack turns a workspace into a solution .zip you can deploy with pac solution import.

To go from nothing to a live agent in a single step, pac copilot init --environment scaffolds, packs, imports, and connects the workspace for you. The individual commands let you drive each part of the loop on its own.

Commands

pac copilot clone

Clone a Copilot Studio agent to a local workspace directory.

pac copilot clone downloads an existing Copilot Studio agent into a local workspace directory, together with the sync metadata that pac copilot pull and pac copilot push rely on. The agent's files are written to a subfolder named after its display name.

Example

pac copilot clone `
   --bot 11111111-1111-1111-1111-111111111111 `
   --environment 22222222-2222-2222-2222-222222222222 `
   --output-dir contoso-support

Required Parameters for copilot clone

--bot -id

The Copilot ID or schema name (unique name found in Bot Details or file name in solution explorer).

Optional Parameters for copilot clone

--component-collection -cc

Component collection ID to clone. Repeat for multiple.

--display-name -dn

Display name of the agent (used for folder naming).

--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.

--output-dir -od

Root folder for clone output. Defaults to current directory.

Remarks

• --bot accepts a Copilot ID or schema name. Pass either the Copilot ID (a GUID) or the agent's schema name. The command resolves a schema name against the target environment.
• The destination subfolder must be empty. Clone writes into a folder named after the agent's (sanitized) display name under --output-dir. If that folder already contains files, clone stops rather than overwrites them. Use --display-name to choose a different folder name.
• Cloning component collections. To bring component collections down alongside the agent, pass one or more collection IDs with --component-collection, separated by semicolons.
• Clone requires an authenticated profile (pac auth create) and resolves the environment from --environment, or from the active profile's organization when you omit it.

pac copilot create

Creates a new copilot using an existing template file as the reference.

Required Parameters for copilot create

--displayName

The display name of the new copilot

--schemaName

The schema name (unique name) of the new copilot.

--solution -s

Name of the solution.

--templateFileName

Source yaml file containing the copilot template that was extracted using the extract-template command.

Optional Parameters for copilot create

--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.

pac copilot delete

Delete a Custom Copilot.

Required Parameters for copilot delete

--bot -id

The Copilot ID or schema name (unique name found in Bot Details or file name in solution explorer).

Optional Parameters for copilot delete

--confirm -y

Required to confirm deletion of the copilot.

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.

pac copilot extract-template

Extracts a template file from an existing copilot in an environment.

Example

This command extracts a template file from an existing copilot in an environment.

pac copilot extract-template `
   --environment 2e250e7a-5607-4fea-aa4e-1aeb7bf79118 `
   --bot 9ee3f7aa-ab79-4cf6-a726-d85c8c18cc3e `
   --templateFileName NewTestCopilot.yaml

The command returns output like the following for a copilot using the English and German languages:

Connected as user@contoso.org

Loaded 34 components for bot 'New Test Copilot ' with id 9ee3f7aa-ab79-4cf6-a726-d85c8c18cc3e. Primary language: English, supported languages: German

New Test Copilot -> C:\Users\user\NewTestCopilot.yaml

Required Parameters for copilot extract-template

--bot -id

The Copilot ID or schema name (unique name found in Bot Details or file name in solution explorer).

--templateFileName

Location of the yaml file to write the copilot template to.

Optional Parameters for copilot extract-template

--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.

--overwrite -o

Allow overwrite of the output data file if it already exists.

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

--templateName

Template name or 'kickStartTemplate' if name is not specified.

--templateVersion

Template version in X.X.X format or 1.0.0 if version is not specified.

pac copilot extract-translation

Extracts file containing localized content for one or more bots.

Example

This command extracts a file containing localized content for one or more copilots.

pac copilot extract-translation `
   --environment 2e250e7a-5607-4fea-aa4e-1aeb7bf79118 `
   --bot 9ee3f7aa-ab79-4cf6-a726-d85c8c18cc3e `
   --all `
   --outdir . `
   --format json

The command returns output like the following:

Connected as user@contoso.org

Loaded 32 components for bot 'New Test Copilot' with id 9ee3f7aa-ab79-4cf6-a726-d85c8c18cc3e. Primary language: English, supported languages: German

Optional Parameters for copilot extract-translation

--all -a

Write localization files for all supported languages. By default, only the primary language is written.

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

--bot -id

The Copilot ID or schema name (unique name found in Bot Details or file name in solution explorer).

--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.

--format

The file format in which to write localized files, either 'resx' or 'json'. The default is 'resx'.

--outdir

The output directory to write to.

--overwrite -o

Allow overwrite of the output data file if it already exists.

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

--sourcedir -src

Source solution directory. When specified, will ignore the connected environment when looking for bots and instead look for content in the solution folder.

pac copilot init

Create a new Copilot Studio agent workspace from a template.

pac copilot init scaffolds a new Copilot Studio agent workspace from a template. It runs in one of two modes, and the presence of --environment decides which mode to use:

• Local scaffold — no --environment. Writes the template files into the project directory and stops. The command doesn't create anything in Dataverse and doesn't require sign-in. Use this mode when you want to author locally and connect to an environment later.
• Bootstrap — --environment supplied. Scaffolds the files, packages them into a solution, imports that solution into the environment, and connects the workspace to the newly created agent. This mode is the one-step path from nothing to a live, sync-ready agent, and it requires an authenticated profile.

Examples

Scaffold a workspace locally:

pac copilot init `
   --name "Contoso Support Agent" `
   --publisher-prefix contoso

Scaffold and bootstrap a live agent in an environment in a single step:

pac copilot init `
   --name "Contoso Support Agent" `
   --publisher-prefix contoso `
   --environment 22222222-2222-2222-2222-222222222222

Scaffold a CLI-authored (CliCopilot) agent into a specific folder:

pac copilot init `
   --name "Contoso Support Agent" `
   --publisher-prefix contoso `
   --authoring-mode cli-copilot `
   --project-dir contoso-support

Required Parameters for copilot init

--name -n

Agent display name.

--publisher-prefix -pp

Publisher customization prefix for the solution.

Optional Parameters for copilot init

--authoring-mode -am

The agent authoring shape to scaffold (default: 'classic'). Use 'cli-copilot' to scaffold a CLI-authored CliCopilot agent.

--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.

--instructions -ins

Agent system instructions.

--project-dir -pd

Target directory for the agent workspace. Defaults to current directory.

--schema-name -sn

Full agent schema name. Overrides the default derivation ({publisher-prefix}_{sanitized-name}). Used as-is without modification.

--template -t

Template profile name (default, minimal). Defaults to 'default'.

Remarks

• The project directory must be empty. init doesn't scaffold over existing files, so point --project-dir to a new or empty folder.
• Schema name derivation. When you omit --schema-name, the agent schema name is built as {publisher-prefix}_{sanitized-name}. Pass --schema-name to set it explicitly; the value is used as-is.
• Bootstrap works for both authoring modes. init --environment bootstraps a live agent in one step for the default classic mode and for --authoring-mode cli-copilot. As an alternative for a CliCopilot agent, you can scaffold locally (no --environment), then run pac copilot pack followed by pac solution import to deploy it yourself.
• Bootstrap creates server-side objects. In bootstrap mode, init imports a solution and creates the agent in the target environment. If an agent with the same schema name already exists, init stops and points you to pac copilot clone to connect to the existing agent instead.
• A brand-new environment can be slow to accept the first import. A freshly created environment might take a minute or two to warm up. An early bootstrap can fail with "Async operations are currently disabled for this organization." Wait a moment and run it again.
• --template (default or minimal) applies to the classic authoring mode only.

pac copilot list

List of copilots in the current or target Dataverse environment.

Example

This command lists all copilots in the current or target Dataverse environment.

pac copilot list --environment 2e250e7a-5607-4fea-aa4e-1aeb7bf79118

The command returns output like the following:

Name                           Bot ID                               Component State Is Managed Solution ID                          Status Code State Code
Ask Me Anything Copilot       584e012c-dc95-46d6-af5a-1263b6a44342 Published       Unmanaged  285af946-6383-49a0-8615-4e2afafeaf38 Active      Provisioned
New Test Copilot               9ee3f7aa-ab79-4cf6-a726-d85c8c18cc3e Published       Unmanaged  285af946-6383-49a0-8615-4e2afafeaf38 Active      Provisioned

Optional Parameters for copilot list

--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.

pac copilot mcp

Information about local MCP (Model Context Protocol) server.

Example

pac copilot mcp --run

Optional Parameters for copilot mcp

--run -r

Run the local MCP (Model Context Protocol) server.

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

Remarks

Learn how to use the Power Platform CLI with built-in MCP server

pac copilot merge-translation

Merge files containing localized content for one or more bots.

Example

This command merges files containing localized content for one or more copilots.

pac copilot merge-translation `
   --environment 2e250e7a-5607-4fea-aa4e-1aeb7bf79118 `
   --file ms_store_newTestCopilot.de-DE.json `
   --solution SolutionName

The command returns output like the following when updating the German language:

Connected as user@contoso.org

Loading language German into bot 'ms_store_newTestCopilot' (New Test Copilot) from file 'C:\Users\user\ms_store_newTestCopilot'. 0 key(s) were missing, 0 value(s) were not used. Use the --verbose switch to get more details.

Updated 16 out of 16 components.

Learn about how to manage errors from the merge-translation command

Optional Parameters for copilot merge-translation

--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.

--file -f

The list of files that contain translations. Glob patterns are supported.

--solution -s

Name of the solution.

--sourcedir -src

Source solution directory. When specified, will ignore the connected environment when looking for bots and instead look for content in the solution folder.

--verbose

Output more diagnostic information during data import/export

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

--whatif

Does not execute the command, but outputs the details of what would happen.

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

merge-translation errors

Based on the example above, if one error exists in the file used to update the copilot, the output looks like:

Connected as user@contoso.org

Loading language German into bot 'ms_store_newTestCopilot' (New Test Copilot) from file 'C:\Users\user\ms_store_newTestCopilot'. 1 key(s) were missing, 1 value(s) were not used. Use the --verbose switch to get more details.

Updated 16 out of 16 components.

The --verbose flag adds details about the error:

Connected as user@contoso.org

Missing translation key: 'dialog(ms_store_newTestCopilot.topic.Lesson2)'.'trigger(main)'.'action(LbWwpD)'.Entity.Definition.'closedListItem(Redmond)'.DisplayName.

Unused translation: 'dialog(ms_store_newTestCopilot.topic.Lesson2)'.'trigger(main)'.'action(LbWwpD)'.Entity.Definition.'closedListItem(Redmont)'.DisplayName, value: Redmond

Loading language German into bot 'ms_store_newTestCopilot' (New Test Copilot) from file 'C:\Users\user\ms_store_newTestCopilot'. 1 key(s) were missing, 1 value(s) were not used. Use the --verbose switch to get more details.

Updated 16 out of 16 components.

pac copilot model list

AI Builder models in the current environment.

Example

This command lists all AI Builder models.

pac copilot model list --environment 2e250e7a-5607-4fea-aa4e-1aeb7bf79118

The command returns output like the following:

Id                                   State    Name
32a9e265-1149-4155-af54-d2856d2b83f5 Active   Document Processing 2023/09/20, 12:21:40
2bcd7b94-50bc-4767-af4a-367c63fb5487 Inactive AI Classify
4e72b59a-17d6-451e-8657-89fbdec56d7a Inactive AI Extract
572f57a7-7a8f-49fc-adb4-331e02c509a6 Inactive AI Reply
b9b636cf-9748-47a7-b617-6df5f00f5151 Inactive AI Sentiment
c076eac8-f218-4feb-8ad1-7ee4fb039419 Inactive AI Summarize
a0440df3-2656-e911-8194-000d3a6cd5a5 Inactive BusinessCard model
62d1e848-5ca7-490a-94bf-79baabe85ef4 Inactive CategoryClassification model
4da7ec17-5c26-4fd2-9ddb-be4f7eda21a9 Inactive DataGenieEmailAddressValidation
51f4da11-5702-401d-b53a-9638744e8ac9 Inactive Document Layout Analysis Model
d1bb8d57-24ab-3b36-9592-bd792e153b79 Inactive DVCopilotQueryModel
3fbd4e5c-32bc-40fc-acce-59c2821cf113 Inactive Empty Dynamic Prompt
8c281981-c5d6-484f-bac7-4924ddd0b8ae Inactive EntityExtraction model
a1afa5d4-7a44-4c31-9cd2-e852a78431fa Inactive GptPromptEngineering model
2c444168-f8b1-4c6a-9313-2d9c03be6fea Inactive Id Scanning Model
77365cfa-7021-4cb7-a9b2-dc9823cde772 Inactive ImageDescription model
aef1bdd2-2a74-4f74-b4eb-9dfa22e35ded Inactive Invoice Model
5ed4d0fd-e9d4-4026-b09b-71f83ea90c60 Inactive Invoice Processing Model
c8425db7-c5a7-4226-b38e-c93a044c0fe1 Inactive KeyPhraseExtraction model
17a6f893-5b0b-4867-8fac-fb2eda9080b2 Inactive LanguageDetection model
046ab801-2756-e911-8194-000d3a6cd5a5 Inactive ObjectDetectionProposal model
892d3698-ba03-3d15-8e9e-843ca4ac5e7d Inactive PowerAppsAppCopilotModel
baa44529-bebe-49e6-837a-80bee63b0d2c Inactive Receipt Scanning Model
f1c549c2-a97e-47a5-b612-c5c2bab0f163 Inactive SentimentAnalysis model
7f8a7856-003a-3662-9871-0000d7674433 Inactive SimsModel
86419a67-205a-454f-b6fc-601394f2786d Inactive TextRecognition model
6225038a-8b5a-4913-bfd2-d8236f4102ba Inactive TextTranslation model
02e1fca3-232a-4f58-8c93-bdd8c9cd6de9 Inactive TextTranslationInternal model

Optional Parameters for copilot model list

--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.

pac copilot model predict

Sends text or prompt to AI Model

Optional Parameters for copilot model predict

--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.

--model-id -id

AI Builder model Id

--model-name -n

Full or partial AI Model name

--prompt -p

Prompt to send to AI Model

--text -t

Text to send to AI Model

pac copilot model prepare-fetch

Takes the FetchXML file from the AI Large Language Model (LLM) and prepares it for execution against the current environment.

Required Parameters for copilot model prepare-fetch

--inputFile -i

Input FetchXML file that usually comes from AI LLM.

--outputFile -o

Output FetchXML file that is ready to execute against the current environment.

Optional Parameters for copilot model prepare-fetch

--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.

pac copilot pack

Package a Copilot Studio agent workspace into a solution zip file.

pac copilot pack packages an agent workspace into a Dataverse solution .zip that you can deploy with pac solution import. It's the standalone form of the packaging step that pac copilot init --environment runs for you, so you can produce the deployable solution as a separate step — for example, in a build pipeline. It works for both classic and CLI-authored (CliCopilot) agent workspaces.

Example

pac copilot pack `
   --publisher-prefix contoso `
   --project-dir contoso-support `
   --output-path out

Required Parameters for copilot pack

--publisher-prefix -pp

Publisher customization prefix for the solution.

Optional Parameters for copilot pack

--output-path -op

Output path for the solution zip file. Defaults to current directory.

--project-dir -pd

Agent workspace directory to package. Defaults to current directory.

--solution-name -sn

Solution unique name. If omitted, derived from the agent schema name.

Remarks

• It's a local operation. Pack reads the workspace and writes a solution .zip. It needs no authentication and no environment, so it's safe to run in a build pipeline.
• The publisher prefix must be valid. --publisher-prefix must be a well-formed customization prefix, or pack stops before writing anything.
• Solution name and output. If you omit --solution-name, the solution's unique name is derived from the agent schema name. The .zip is written to the current directory unless you set --output-path.
• Pack doesn't deploy. It produces the solution but doesn't import it. Follow it with pac solution import to deploy the agent, then pac copilot clone if you want a sync-connected workspace for it.

pac copilot publish

Publish a Custom Copilot

Required Parameters for copilot publish

--bot -id

The Copilot ID or schema name (unique name found in Bot Details or file name in solution explorer).

Optional Parameters for copilot publish

--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.

pac copilot pull

Pull remote changes from Copilot Studio and merge with local workspace.

The pac copilot pull command fetches the current server state of the agent and merges it into your local workspace by using a three-way merge. This process ensures that server-side edits and your untouched local files both stay intact. Run it before you start editing, and run it again before you push your changes.

Example

Run the command from inside the workspace folder:

pac copilot pull

Or point it at a workspace elsewhere on disk:

pac copilot pull --project-dir contoso-support

Optional Parameters for copilot pull

--project-dir -pd

Path to the project directory. Defaults to the current working directory.

Remarks

• Run it inside a sync workspace. The pull command works only in a folder created by pac copilot clone or pac copilot init. It reads the target environment and agent from the workspace's sync metadata, which is why there's no --environment argument. If you run it anywhere else, it fails with a "workspace not found" error.
• It writes to your local files. Pull merges remote changes into the workspace and downloads knowledge files. Commit or back up local work you care about before pulling.
• Sign in first with pac auth create.

pac copilot push

Push local workspace changes to Copilot Studio.

pac copilot push sends the changes in your local workspace back to the agent in Dataverse. It compares your files against the last-known server state, uploads only what changed - including knowledge files, cloud flows, and connection references - and reports what it pushed.

Example

Run it from inside the workspace folder:

pac copilot push

Or point it at a workspace elsewhere on disk:

pac copilot push --project-dir contoso-support

Optional Parameters for copilot push

--project-dir -pd

Path to the project directory. Defaults to the current working directory.

Remarks

• Run it inside a sync workspace. Like pull, push only works in a folder created by pac copilot clone or pac copilot init. It reads the target environment from the workspace's sync metadata. There's no --environment argument.
• Pull first if there's a conflict. If the same item changed both locally and on the server, push stops and asks you to run pac copilot pull before trying again. This process keeps a push from silently overwriting a server-side change you didn't see.
• No local changes is a no-op. If push finds nothing to send, it reports that and exits without touching the environment.
• A successful push mutates the live agent in the target environment.
• Sign in first with pac auth create.

pac copilot quarantine

Quarantine status of copilot agent.

Required Parameters for copilot quarantine

--bot-id -id

The ID of the copilot to quarantine/unquarantine.

Optional Parameters for copilot quarantine

--environment -env

Environment (ID, org ID, url, unique name, or partial name).

--status -s

Quarantine status value. true = quarantine, false = unquarantine. Defaults to true.

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

pac copilot status

Poll the deployment status of a specified copilot in the current or target Dataverse environment.

Example

This command polls the deployment status of a specified copilot in the current or target Dataverse environment.

pac copilot status `
   --environment 2e250e7a-5607-4fea-aa4e-1aeb7bf79118 `
   --bot-id 9ee3f7aa-ab79-4cf6-a726-d85c8c18cc3e

The command returns output like the following:

Connected as user@contoso.org
Connected to... Contoso Organization
Virtual Agent New Bot German with ID 9ee3f7aa-ab79-4cf6-a726-d85c8c18cc3e has been provisioned.

Required Parameters for copilot status

--bot-id -id

The ID of a copilot (Chatbot).

Optional Parameters for copilot status

--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.

Authentication and environment for the sync commands

The clone, pull, push, and init --environment commands all talk to a Dataverse environment, so they need an authentication profile. Sign in first with pac auth create.

• clone, pull, and push require an active profile. pac copilot init only needs one when you pass --environment; without it, init scaffolds files locally and needs no sign-in.
• pull and push read the target environment from the workspace's sync metadata, so they don't take an --environment argument. clone and init do.
• pac copilot pack is purely local. It reads and writes files only, so it needs no authentication and no environment.

pull and push only work inside a workspace created by clone or init. The sync metadata written when the workspace is created is what tells them which agent and environment to talk to, so running them anywhere else fails fast with a "workspace not found" error.

See also

Microsoft Power Platform CLI Command Groups
Microsoft Power Platform CLI overview