Push/pull Copilot Studio agent content via the VS Code extension's LanguageServerHost LSP binary. Handles authentication (interactive browser login for push/pull, device code flow for chat token), sync push, sync pull, clone, and diff operations.
Push and pull Copilot Studio agent content by calling the VS Code extension's LanguageServerHost binary directly, using the same custom LSP protocol the extension uses internally.
This is a new capability under active development. The manage-agent scripts (manage-agent.bundle.js, chat-with-agent.bundle.js) are pre-built bundles that must not be modified, patched, or monkey-patched. If a script fails:
ms-copilotstudio.vscode-copilotstudio).auth command). If --client-id is omitted, the script uses VS Code's first-party client ID with interactive browser login instead..mcs/conn.json inside a cloned agent workspace (created automatically during clone).Search for .mcs/conn.json in the workspace and nearby directories to find existing connection details. The script auto-reads environment details from conn.json. If no conn.json is found, ask the user for the required parameters.
There are two different auth flows depending on the operation:
These commands use VS Code's first-party client ID with the Island API gateway. Authentication is interactive — a browser window opens automatically for sign-in. No manual code entry is needed.
No separate auth step is needed before push/pull. The commands handle token acquisition automatically. Just run the command directly (Phase 2).
auth command (device code flow — chat/test token)The auth command acquires a generic api.powerplatform.com token using device code flow. This token is used by the chat and test skills, not by push/pull.
Run with a 5-minute timeout:
node .github/scripts/manage-agent.bundle.js auth \
--tenant-id "<tenantId>" \
--client-id "<clientId>" \
--environment-url "<environmentUrl>"
Timeout: 300000ms (5 minutes) — set this on the Bash tool call.
Tokens and MSAL refresh tokens are persisted in the OS credential store (macOS Keychain, Windows DPAPI, Linux secret-tool). After initial authentication:
The script emits a JSON line to stdout:
{"status":"device_code","userCode":"XXXXXXXX","verificationUri":"https://login.microsoft.com/device","message":"...","expiresIn":900}
When you see this in the output, immediately tell the user:
Authentication Required
Please open {verificationUri} in your browser and enter code {userCode}
The command is waiting for you to complete sign-in. You have {expiresIn/60} minutes.
The command will automatically continue once the user completes authentication. Do NOT cancel the command — it is waiting for the browser sign-in to complete.
Two tokens are acquired sequentially (Copilot Studio API, then Dataverse API), so the user may need to authenticate twice on first use.
status: "ok"Tokens are cached. Proceed to Phase 2.
device_code_expiredThe user didn't authenticate in time. Re-run the auth command and remind them to authenticate promptly.
All commands auto-detect the agent directory (finds the subfolder with .mcs/conn.json) and read connection details from it.
--client-id is optional. When omitted, uses VS Code's 1p client with interactive browser login.
node .github/scripts/manage-agent.bundle.js pull \
--workspace "<path-to-agent-folder>" \
--tenant-id "<tenantId>" \
--environment-id "<envId>" \
--environment-url "<envUrl>" \
--agent-mgmt-url "<mgmtUrl>"
MANDATORY: Before executing push, ALWAYS invoke /copilot-studio:pre-push-review first. Never push without the review gate. The only exception is --force flag explicitly requested by the user after a warning.
Important: Always pull before push to get fresh row versions. If you push without pulling first, you'll get a ConcurrencyVersionMismatch error.
--client-id is optional. When omitted, uses VS Code's 1p client with interactive browser login.
node .github/scripts/manage-agent.bundle.js push \
--workspace "<path-to-agent-folder>" \
--tenant-id "<tenantId>" \
--environment-id "<envId>" \
--environment-url "<envUrl>" \
--agent-mgmt-url "<mgmtUrl>"
Requires --agent-id (the bot GUID from list-agents). Uses Island API token automatically.
node .github/scripts/manage-agent.bundle.js clone \
--workspace "<target-folder>" \
--tenant-id "<tenantId>" \
--environment-id "<envId>" \
--environment-url "<envUrl>" \
--agent-mgmt-url "<mgmtUrl>" \
--agent-id "<agentId>"
--client-id is optional. When omitted, uses VS Code's 1p client with interactive browser login.
node .github/scripts/manage-agent.bundle.js changes \
--workspace "<path-to-agent-folder>" \
--tenant-id "<tenantId>" \
--environment-id "<envId>" \
--environment-url "<envUrl>" \
--agent-mgmt-url "<mgmtUrl>"
Uses Dataverse REST API directly (no LSP binary needed). --client-id is optional.
node .github/scripts/manage-agent.bundle.js list-agents \
--tenant-id "<tenantId>" \
--environment-url "<envUrl>" \
[--no-owner]
By default lists only agents owned by the current user. Add --no-owner to list all unmanaged agents.
Uses BAP REST API directly (no LSP binary needed). --client-id is optional.
node .github/scripts/manage-agent.bundle.js list-envs \
--tenant-id "<tenantId>"
All commands output JSON to stdout with a status field:
{"status":"device_code","userCode":"XXXXXXXX","verificationUri":"https://login.microsoft.com/device","message":"...","expiresIn":900}
{"status":"ok","method":"powerplatformls/syncPull","result":{...}}
{"status":"error","error":"description of what went wrong"}
| Error | Likely cause | Resolution |
|---|---|---|
| Extension not found | Copilot Studio VS Code extension not installed | Install from VS Code marketplace |
| LSP request timed out | Binary not responding or wrong protocol version | Check extension version, try updating |
| device_code_expired | User didn't authenticate in time | Re-run auth, authenticate promptly |
| ConcurrencyVersionMismatch | Push without fresh row versions | Pull first, then push |
| Token expired + silent refresh failed | Refresh token expired (~90 days) | Run auth command for new device code flow |
| Binary missing | Extension installed but binary not present | Reinstall the extension |