Microsoft.Agents.Hosting.Cli 0.2.132-beta

Prefix Reserved
This is a prerelease version of Microsoft.Agents.Hosting.Cli.
dotnet tool install --global Microsoft.Agents.Hosting.Cli --version 0.2.132-beta
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Microsoft.Agents.Hosting.Cli --version 0.2.132-beta
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Microsoft.Agents.Hosting.Cli&version=0.2.132-beta&prerelease
                    
nuke :add-package Microsoft.Agents.Hosting.Cli --version 0.2.132-beta
                    

Microsoft.Agents.Hosting.Cli (msagent)

Microsoft.Agents.Hosting.Cli is a .NET command-line tool for working with Microsoft Agent Hosting resources. It helps developers and automation workflows authenticate, select a target environment, manage agents, and manage deployments.

This tool is intended for both humans and coding agents that need a consistent command interface to interact with the Agent Hosting platform.

What this tool does

The CLI supports the following core activities:

  • Sign in and manage authentication state
  • List and select Power Platform environments
  • Create, copy, list, show, pull, and delete agent resources
  • Manage deployment lifecycle and connection configuration

Install

The tool requires the .NET 10 and ASP.NET Core 10 runtimes. The telemetry SDK adds the ASP.NET Core shared-framework dependency.

Download .NET 10 from https://dotnet.microsoft.com/download/dotnet/10.0. Installing the .NET 10 SDK includes both runtimes and provides the dotnet tool install command used below. If you only run an already-installed tool, the ".NET Runtime" and "ASP.NET Core Runtime" installers are enough. On Windows you can also use winget:

winget install Microsoft.DotNet.SDK.10

Verify that both runtimes are present (look for Microsoft.NETCore.App 10.x and Microsoft.AspNetCore.App 10.x):

dotnet --list-runtimes

Install the tool as a global .NET tool:

dotnet tool install --global Microsoft.Agents.Hosting.Cli

Then run the command:

msagent --help

To update to the latest version:

dotnet tool update --global Microsoft.Agents.Hosting.Cli

For preview releases, add --prerelease. For a local tool, omit --global and update from its manifest directory; for a custom installation, use --tool-path <directory> instead.

In a terminal, msagent checks listed versions on nuget.org and shows an update notice on stderr before command output or prompts. Newer prereleases are labeled (prerelease) and include the preview update command. It never installs an update automatically.

Successful checks are cached for 24 hours. Feed requests share a three-second deadline; failures are silent and retried no sooner than one hour later when the cache is writable. Checks are skipped for help, version, invalid/navigation-only commands, --json, CI, or redirected stdout/stderr. Set AH_CLI_SKIP_UPDATE_CHECK=true (case-insensitive) or 1 to disable checks and notices. --non-interactive alone does not disable the check.

Command overview

msagent [command] [options]

Common command groups include:

  • msagent auth — sign in, check auth state, switch accounts, sign out
  • msagent env — list available environments and select a target environment
  • msagent agent — create, copy, initialize, list, show, pull, delete, deploy, and evaluate agents
  • msagent deployment — manage deployment records and connection binding
  • msagent test ask — send a live query to a selected Copilot Studio agent
  • msagent test playground — launch the M365 Agents Playground for a selected agent

Live test commands are available by default. They perform live operations that can have real effects; use only an approved agent and destination. See the live testing command reference for target selection, prerequisites, and behavior.

Global options:

-j,  --json              Emit machine-readable JSON output
-nc, --no-color          Disable colored output
-ni, --non-interactive   Fail instead of opening browser-based authentication flows
-h,  --help              Show help and usage information
-v,  --version           Show version information

Typical workflow

  1. Sign in to the tenant or account you want to work with.
  2. List and select the target environment.
  3. Create or initialize an agent project.
  4. Create an MCS deployment and deploy the MCS project to it.
  5. Configure deployment connections as needed.
  6. Evaluate the agent with msagent agent eval run, and review the results with msagent agent eval list / show.

Example usage

Sign in

msagent auth create

Check authentication status

msagent auth status

List environments

msagent env list

Select an environment

msagent env select <environment-id>

Create an agent

msagent agent create --agent-type MCSAgent --agent-name "Contoso Agent" --description "Contoso helper" --initial-prompt "Help users with Contoso questions."

Copy an agent

Creates a new, independent agent from an existing one and registers it locally. Nothing is sent to Copilot Studio and the source is never changed; the copy's first deploy creates its own agent.

msagent agent copy --mcs-clone-agent-id <agent-id> --environment-id <environment-id> --agent-name "Contoso Agent copy"

List agents

msagent agent list

Show a project or agent configuration

msagent agent show

Evaluate an agent

Runs the same Copilot Studio evaluation the maker portal runs, and the results appear there beside the ones started from the portal. Evaluations consume Copilot Credits; the cost is reported when the run finishes.

Start from the portal's CSV template — conversationNumber, question, response — and run it in one line. --name names the test set this creates, and --watch waits for the grader:

msagent agent eval run --from-csv EvalConversationTemplate.csv --name EvaluationV1 --watch

A test set is durable: create it once, run it as often as you like.

msagent agent eval run --testset EvaluationV1 --watch

To have Copilot Studio invent the conversations instead of supplying a file:

msagent agent eval run --generate 10 --turns 3 --name "Smoke tests" --watch

Review what has run, and read one run back:

msagent agent eval list
msagent agent eval show --run-id <run-id>

Read the conversations the agent actually had. The terminal view shortens long replies; --output writes the whole thing to a file you can open:

msagent agent eval show --run-id <run-id> --conversation 2
msagent agent eval show --run-id <run-id> --transcript
msagent agent eval show --run-id <run-id> --output run.md

Manage the test sets themselves:

msagent agent eval testset list
msagent agent eval testset export --testset EvaluationV1 --output conversations.csv
msagent agent eval testset update --testset EvaluationV1 --from-csv conversations.csv --replace

A queued or in-progress run can be stopped, and a finished one deleted. Deleting a run leaves the test set it used in place:

msagent agent eval cancel --run-id <run-id>
msagent agent eval delete --run-id <run-id>

JSON output

For automation and agent-driven workflows, pass --json to emit structured output:

msagent env list --json
msagent agent list --json

This is especially useful for coding agents that need to inspect tool output programmatically.

Non-interactive mode

Use --non-interactive=true for scripts that must not open identity UI. Explicit interactive create/login, including device code, return 12007 / exit 3 before cache enumeration; a cached account does not bypass this. --json alone is not non-interactive. Eligible workload credentials still require appropriate tenant permissions:

msagent auth create --managedIdentity --non-interactive=true

Authentication profiles and clouds

Create an owned profile, then use token-free metadata commands to inspect and select it:

msagent auth create -n Dev -ci Public
msagent auth list
msagent auth select --name Dev
msagent auth who
msagent auth name --index 1 --name Development
msagent auth delete --index 1

Names are 1–30 characters and case-sensitive unique. List positions are transient and 1-based. Select accepts exactly one --index or --name, or an interactive metadata picker without selectors. List and picker rows show full profile tenant IDs ((none) when missing) and use the application ID for non-user profiles without an account name, without authenticating. Delete requires exactly one selector. Renaming an inactive profile does not activate it. auth clear repairs corrupt metadata and removes only owned msagent profiles/credentials/caches, not PAC/Azure/broker state or source certificates.

Create uses --cloud / -ci: Public (default), Preprod, Test, UsGov, UsGovHigh, UsGovDod, China, UsNat, UsSec. Authentication has no separate ring option. Unsupported China derived routes and UsNat/UsSec Copilot Studio gateways fail closed; a stored profile does not prove downstream service support.

Create's other local aliases are --name -n, --environment -env, --tenant -t, --deviceCode -dc, --username -un, --password -pw, --applicationId -id, --clientSecret -cs, --certificateDiskPath -cdp, --certificatePassword -cp, --managedIdentity -mi, --githubFederated -ghf, --azureDevOpsFederated -adof. Credential modes are exclusive; username/password must be paired. Client secret, PFX certificate and federation require explicit tenant/application GUIDs. DefaultAzureCredential is configured source selection, not a guarantee that managed identity wins. Developer-source renewal cannot launch Azure CLI/PowerShell/azd when interaction is forbidden. ROPC cannot satisfy MFA and its password is not persisted for renewal.

Passwords/secrets in arguments can be exposed by shell history and process inspection despite CLI redaction. Owned client secrets, PFX passwords and caches require protected native storage; a token-cache-only plaintext baseline never permits plaintext credentials. Federation assertions are not persisted. GitHub federation uses ACTIONS_ID_TOKEN_REQUEST_URL/TOKEN; Azure DevOps uses MSAGENT_ADO_ID_TOKEN_REQUEST_URL/TOKEN, both with audience api://AzureADTokenExchange. Native storage and sovereign downstream operation require platform/service validation. Installing .NET alone does not establish protected-store, system-browser or broker readiness; locked or headless sessions may still be unavailable.

auth status keeps its existing JSON/exit contract. Status/list/select/who never acquire tokens or unlock native stores. Caller cancellation returns 130 and can report safe committed/cleanup guidance; it does not promise rollback. Inspect metadata before another mutation and retry intended owned cleanup with auth clear after repairing storage. Partial deletion reports the profile selected at commit, or that no active profile remained.

The environment selection follows the profile

Target precedence is an explicit command environment, a compatible owned override, the profile's default, then a missing-target error. env select updates the selected profile's default:

msagent env list
msagent env select <environment-id>
msagent auth who

Foreign/incompatible overrides are not silently adopted. To change another profile's default, first select that profile with auth select, then use env select.

Telemetry

The CLI sends usage telemetry (command names and outcomes, never argument values, paths, tokens, or other command content). To learn more, see the Privacy Statement below.

To opt out, use either of the following:

# Persistent: saved preference
msagent telemetry disable

# Current process only
AH_CLI_TELEMETRY_OPTOUT=1 msagent --help

In PowerShell, set the variable for the current session:

$env:AH_CLI_TELEMETRY_OPTOUT = "1"

To opt back in, run msagent telemetry enable and set AH_CLI_TELEMETRY_OPTOUT to 0 or false (or remove it). Run msagent telemetry status to check the current setting. AH_CLI_TELEMETRY_OPTOUT accepts 1/true to disable and 0/false to enable; any other nonempty value is treated as opted out.

Notes

  • The CLI is designed to be used from a shell or automation environment.
  • Commands are generally safe for deterministic scripting when used with --json and --non-interactive as appropriate.
  • The CLI supports TLS 1.3 and TLS 1.2.
  • For full command details, run:
msagent --help
msagent <command> --help

Privacy Statement

We value your privacy. To learn more about how your data is handled when using the AgentHosting CLI, please review our Privacy Statement: https://www.microsoft.com/en-us/privacy/privacystatement

Summary

AgentHosting CLI gives developers and coding agents a single entry point for authenticating, selecting environments, preparing agent resources, and managing deployment configuration in an Agent Hosting environment. It is intentionally designed to be scriptable, readably structured, and easy to use from both terminal workflows and automated tooling.

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
0.2.132-beta 0 11/18/2026
0.2.128-beta 34 11/17/2026
0.2.125-beta 84 11/14/2026
0.2.117-beta 71 11/13/2026
0.2.96-beta 74 11/12/2026
0.2.88-beta 68 11/11/2026
0.2.83-beta 66 11/10/2026
0.2.75-beta 78 11/3/2026
0.2.64-beta 79 11/2/2026
0.2.56-beta 91 10/31/2026
0.2.52-beta 95 10/28/2026
0.2.47-beta 105 10/24/2026
0.2.41-beta 92 10/23/2026
0.2.37-beta 105 10/22/2026
0.2.30-beta 92 10/22/2026
0.2.27-beta 92 10/21/2026
0.2.20-beta 99 10/20/2026
0.2.18-beta 100 10/19/2026
0.2.16-beta 120 10/17/2026
0.2.12-beta 107 10/16/2026
Loading failed