Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The Agent 365 CLI is a cross-platform command-line tool for deploying and managing Agent 365 applications on Azure. This reference explains how to install, update, uninstall, and use the CLI for automation and troubleshooting.
You don't need to install the CLI manually. Agent 365 Skills check for the CLI, install or update it automatically, and run all required commands on your behalf. This article is a reference for developers who need to install or use the CLI directly - for example, when building CI/CD automation, troubleshooting a specific step, or working without an AI coding agent.
Note
The complete developer workflow - including AI-guided setup, role guidance, and post-deployment steps - is in Get started with Agent 365 development. This article is the CLI reference: installation, update, uninstall, available commands, and troubleshooting.
Prerequisites
The CLI requires .NET 8.0 or later. For all other prerequisites, including an Azure subscription and required Entra roles, see Quickstart: Connect an existing agent to Agent 365.
Microsoft Entra authentication
By default, Agent 365 setup uses the Microsoft-managed Agent 365 CLI enterprise application when it's available in your tenant.
| Property | Value |
|---|---|
| Display name | Agent 365 CLI |
| Application (client) ID | f54280f4-395e-4ea8-9e48-bf2d4952aa14 |
To verify the application, go to the Microsoft Entra admin center, select Enterprise applications > All applications, and search for the application ID. The service principal's Object ID is unique to your tenant. Don't use the Object ID where the CLI or documentation asks for an application (client) ID.
The CLI checks for the enterprise application's service principal in your tenant and validates the required delegated scopes in the access token. It doesn't create or modify Microsoft's application registration. The Microsoft-managed application doesn't elevate the signed-in user, bypass Conditional Access or Security Defaults, or remove separate consent requirements for agent resources.
If the Microsoft-managed enterprise application isn't available, config-free setup looks for a tenant-owned app named Agent 365 CLI. Existing configurations that specify a custom clientAppId remain supported. For instructions, see Custom client app registration for Agent 365 CLI.
The Microsoft-managed application uses these interactive authentication methods:
| Environment | Authentication method |
|---|---|
| Native Windows | Web Account Manager (WAM) |
| Windows Subsystem for Linux (WSL), macOS, and Linux | Device code |
Tenant-owned custom applications use the system browser when WAM isn't available.
Install the Agent 365 CLI
Use the following steps to install the Agent 365 CLI globally on your operating system.
Prerequisites
You must have .NET installed. (.NET 8.0 is recommended.)
Use dotnet tool install
Install the Agent 365 CLI by using the following command:
dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli
For the latest instructions and available versions, visit the official NuGet page: Microsoft.Agents.A365.DevTools.Cli on NuGet.org
Verify installation
After installing the Agent 365 CLI, verify that it's properly installed by running the --help command:
a365 -h
This command displays the help information and confirms the CLI is ready to use.
Update the Agent 365 CLI
Update Agent 365 CLI by using the dotnet tool update command:
dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli
Note
To update Agent 365 CLI, you need an internet connection to access the latest NuGet package: Microsoft.Agents.A365.DevTools.Cli.
Uninstall the Agent 365 CLI
Uninstall Agent 365 CLI by using the dotnet tool uninstall command:
dotnet tool uninstall --global Microsoft.Agents.A365.DevTools.Cli
Agent 365 CLI file locations
The default location for a tool's executable file depends on the operating system:
| OS | Path |
|---|---|
| Linux/macOS | $HOME/.dotnet/tools |
| Windows | %USERPROFILE%\.dotnet\tools |
The SDK adds this location to your path when you first run it. So you can invoke global tools from any directory without specifying the tool location.
Tool access is user-specific, not machine global. A global tool is only available to the user that installs the tool.
Agent 365 CLI commands
For the complete list of available commands, use the --help command or see Agent 365 CLI Reference.
Tip
You don't need to run CLI commands manually. Agent 365 Skills automate the full workflow - CLI installation, configuration, blueprint setup, deployment, and publishing - using an AI coding agent. Use the CLI reference here if you're building CI/CD automation, troubleshooting a specific step, or working without an AI coding agent.
For complete instructions on how to set up an Agent 365 agent by using the CLI, see Get started with Agent 365 development.
Troubleshooting
This section provides information about how to troubleshoot errors with Agent 365 CLI.
Tip
Agent 365 Troubleshooting Guide contains high-level troubleshooting recommendations, best practices, and links to troubleshooting content for each part of the Agent 365 development lifecycle.
CLI-specific issues covered in this section:
- Microsoft-managed Agent 365 CLI application isn't available
- Device code authentication is blocked
- Authentication fails with AADSTS70007
- Required delegated scopes are missing
- Agent doesn't appear in Teams
- Can't create agent instance in Teams
Microsoft-managed Agent 365 CLI application isn't available
Update the CLI and run a365 setup requirements again. To verify whether the staged rollout reached your tenant, search Enterprise applications in Microsoft Entra for application ID f54280f4-395e-4ea8-9e48-bf2d4952aa14.
If the service principal isn't present, setup falls back to a tenant-owned app named Agent 365 CLI. If you don't already have that app, follow Custom client app registration for Agent 365 CLI.
Device code authentication is blocked
The Microsoft-managed application uses device code authentication on WSL, macOS, and Linux. Security Defaults or a Conditional Access policy can block this flow and return AADSTS530035.
Don't disable your organization's security policy to work around this error. Run the CLI on native Windows to use WAM, or work with your identity administrator to use a tenant-owned custom application and an authentication flow that your policy permits.
Authentication fails with AADSTS70007
Older CLI versions might use an unsupported browser response mode with the Microsoft-managed application and return AADSTS70007. Update to the latest CLI version and retry:
dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli
Required delegated scopes are missing
The CLI validates the Microsoft-managed application's effective delegated permissions from the access token's scp claim. Update the CLI and rerun a365 setup requirements.
Don't add redirect URIs, optional claims, API permissions, or tenant-local permission grants to the Microsoft-managed application. If validation still reports missing scopes, capture the trace and correlation IDs from the error and contact Microsoft support. If you use a tenant-owned app, follow the validation steps in Custom client app registration for Agent 365 CLI.
Agent doesn't appear in Teams
Create agent instances troubleshooting: Agent doesn't appear in Teams
Can't create agent instance in Teams
Create agent instances troubleshooting: Can't create agent instance in Teams