| name | copilot-cli |
| description | Use this skill for service operations only. DO NOT use this skill for CLI implementation lifecycle work such as creating, testing, updating, troubleshooting, validating, removing, or documenting the CLI tool itself; delegate those tasks to cli-tool-expert. Execute Copilot Studio operations using the `copilot` CLI tool. CLI interface for Microsoft Copilot Studio agents via Dataverse API. Triggers: copilot, copilot cli, copilot studio, copilot agent, manage copilot agents, copilot studio agents, copilot topics, copilot knowledge, copilot tools, copilot connectors, power platform copilot, copilot flows, copilot solutions, copilot prompts, copilot models, copilot environment, copilot connections |
Execute Copilot Studio operations using the `copilot` CLI. All Copilot Studio interactions should use this CLI.
<quick_start>
The copilot CLI follows this pattern:
copilot <command-group> <action> [arguments] [options]
| Command | Description |
|---|
copilot agent list --table | List all agents with formatted output |
copilot agent get <id> | Get agent details by GUID |
copilot agent create --name "Name" | Create a new agent |
copilot agent prompt <id> -m "msg" | Send a message to an agent |
copilot agent publish <id> | Publish agent changes |
copilot agent knowledge list <id> | List agent knowledge sources |
copilot agent tool list -a <id> | List tools attached to an agent |
copilot agent topic list -a <id> |
- **whoami** — Current user info (ID, business unit, org)
- **auth** — Login, logout, status, refresh, test credentials
- **auth** -- Authentication commands and nested `auth profiles` management
- **agent** — Core agent CRUD, publish, prompt; subgroups: knowledge, topic, trigger, tool, transcript, analytics, auth, model, channel
- **solution** — Solution lifecycle (create, export, import); subgroups: agent, connection-reference, custom-connector, component, publisher
- **powerautomate-flow** — List/inspect Power Automate cloud flows
- **agent-flow** — Agent flow lifecycle (create, export, import, test, enable/disable); subgroups: runs, scaffold
- **tool** — Discover tools (prompts, MCP, connectors); subgroups: restapi, mcp
- **prompt** — AI Builder prompt lifecycle (create, update, run, publish); subgroups: permissions, auth
- **model** — AI Builder model management (list, enable, disable)
- **managed-connector** — Browse Microsoft's built-in connector catalog
- **custom-connector** — Custom connector lifecycle (create from OpenAPI, validate, register, remove)
- **connections** — Manage authenticated connections (credentials); subgroup: onedrive
- **connection-references** — Solution-aware connection pointers (create, update, remove)
- **environment** — Power Platform environment management (list, select, create, delete)
- **admin** — Auth identity management (app registrations, service principals)
- **user-licenses** — Check M365 license assignments via Microsoft Graph
**`copilot agent update --instructions-file ` and `--response-format-file ` write into TemplateLine fields whose default template format is Power Fx.** Power Fx treats `{ ... }` as a record literal, so a JSON example inside the file (e.g. `{ "summary_markdown": "..." }`) breaks `copilot agent publish` with:
**For integrated-auth agents ("Authenticate with Microsoft"), `copilot agent prompt` uses the M365 Agents SDK and derives the Power Platform cloud automatically from the environment's Dataverse host** — no cloud config is needed for normal commercial tenants (`*.crm.dynamics.com` → public cloud `api.powerplatform.com`). Sovereign clouds are mapped from the Dataverse host too: GCC (`*.crm9.dynamics.com`), GCC High (`*.crm.microsoftdynamics.us`), DoD (`*.crm.appsplatform.us`), China (`*.crm.dynamics.cn`).
**If `copilot agent prompt` authenticates, opens a conversation, and delivers the message but the agent replies with `Error code: EnvironmentGroupPolicyViolation`, the environment's Power Platform environment-group rule is blocking direct chat channels at runtime.** The block is transport-independent for direct paths (Direct Line and M365 SDK Direct-to-Engine fail identically) but does NOT apply to connector invocation: the same agent answers normally through the Microsoft Copilot Studio connector (`ExecuteCopilotAsyncV2`) inside a Power Automate/agent flow (`copilot agent-flow test --trigger manual --body-file --wait`).
**`copilot agent prompt` in M365 SDK mode fails with `--client-id or ENTRA_CLIENT_ID env var required` unless the auth profile's `.env` sets `ENTRA_CLIENT_ID=`** (an app with delegated `CopilotStudio.Copilots.Invoke` consented, e.g. the psdxautomation app `12d53a00-9654-4398-9855-a8517fb732c4`). The MSAL token cache lives at `/cache/.m365-token-cache.json` and is a standard MSAL `SerializableTokenCache` JSON — a cache from another tool using the same client id + tenant (e.g. AgentTrainer's `/msal_cache.bin`) can be copied there to skip the device-code sign-in; MSAL silently exchanges the refresh token for the `https://api.powerplatform.com/.default` scope.
**If `copilot agent prompt` reaches the agent but fails with HTTP `405` while the active profile has a service-principal secret (`AZURE_CLIENT_SECRET`/`M365_SDK_CLIENT_SECRET`), the environment does not allow app-only (service principal) access to Copilot Studio conversations.** The Direct-to-Engine endpoint returns `App-only S2S access is not enabled for this environment.`
**A profile that sets `AZURE_TENANT_ID` + `AZURE_CLIENT_ID` + `AZURE_CLIENT_SECRET` (in addition to `DATAVERSE_URL`) automatically switches ALL Dataverse Web API command groups** — `connections`, `connection-references`, `agent-flow`, `solution`, `agent` CRUD (everything routed through `client.get_client()`) — **to MSAL client-credentials auth instead of `az login`.** `Config.get_auth_method()` is the single source of truth: it returns `service_principal` only when all four fields are present (`has_service_principal_auth()`), otherwise `azure_cli`. This is a deterministic per-profile choice, not a try-then-fallback — a profile is either fully opted into service-principal auth or it uses delegated `az login` auth, never both in the same call.
`copilot auth status --profile default` can exit `2` for an unauthenticated
profile while still returning structured JSON that includes `"authenticated":
false`. Treat that as status data, not an unhandled tool failure, when the probe
is intentionally checking auth state. Wrap the command per the cli-tool
`Shape Expected Auth Status Probes` rule and validate both exit status `2` and
the unauthenticated evidence before exiting `0`.
Copilot auth profile names are local runtime state. Do not infer the Progress
profile name from the tenant or this skill; first run
`copilot auth profiles list --table`, then use the discovered profile name for
the whole command batch. The Progress profile should set
`AZURE_CLI_EXPECTED_USER` to `psdxautomation@progress.com` and the tenant to
`db266a67-cbe0-4d26-ae1a-d0581fe03535`. Before redirecting data commands such
as `copilot agent model list --profile "$profile"` or
`copilot agent list --profile "$profile"` into JSON files, run a shaped auth
preflight and preserve the producer status:
`copilot agent list` emits JSON. JSON is already the default. Do not add `--format json`,
`--json`, or any output flag not listed for the leaf command. `copilot agent --help`
is group help only; before adding flags, inspect `usage.json` at
`commands.agent.commands.list.options` or run `copilot agent list --help`.
Use `--table` only when human-readable output is requested.
**The `copilot agent channel` subgroup is read-only — `list`, `get`, and `get-token` only.** There is no CLI command, and no supported Microsoft API, to *enable* a channel or *retrieve* the Web/Direct Line channel secret. The official Power Platform "PVA Bots" REST API exposes only quarantine operations, and Microsoft's own Copilot Studio Kit requires the Direct Line secret to be pasted in by hand. Enabling Teams and reading the secret are manual Copilot Studio portal actions:
**Do not use `Microsoft.PowerApps.Administration.PowerShell` on macOS as a substitute for missing `copilot` DLP policy commands.** Microsoft's Power Platform PowerShell docs require Windows PowerShell 5.x and .NET Framework; PowerShell 6+ uses .NET Core and is incompatible with those modules. On macOS, `Get-AdminDlpPolicy` can fail during module auth with `System.Windows.Forms` / `WithAuthority` assembly errors because the module's auth helper calls Windows Forms APIs. Treat DLP policy reads and changes as Power Platform admin/portal work unless the CLI grows a first-class, tested Dataverse/Power Platform API path.
`pac` is not interchangeable with the repo-owned `copilot --profile ` auth profile. Before using `pac` as evidence, run `pac auth who` and prove the tenant, environment, and user match the target Copilot Studio environment. A stale/default `pac` profile can point at Adam's personal default tenant while `copilot --profile psdxautomation` points at a Progress/PSDX tenant. `pac` has copilot publish/status and connector list commands, but no verified DLP policy command and no portal-only channel enablement or Direct Line secret retrieval surface.
**Tools and knowledge can be attached while authoring without Copilot Studio capacity. Before `copilot agent publish`, the CLI runs a fail-fast capacity pre-check on the target Power Platform environment. If the environment has no Copilot Studio capacity, publishing is blocked with a non-zero exit BEFORE the publish mutation.** Agent create/update and tool/knowledge attachment are not capacity-gated.
